[Python] uv 사용법

설치

# 리눅스
curl -LsSf https://astral.sh/uv/install.sh | sh

# 맥 homebrew
brew install uv

# With pip.
pip install uv

사용법

파이썬 설치 & 설치된 파이썬 리스트 조회 & 특정 버전 제거

아래와 같이 명령어를 사용하면 가장 최신 배포된 파이썬 버전을 설치합니다.

# 파이썬 버전 설치
uv python install 3.12

Installed Python 3.12.11 in 1.35s
 + cpython-3.12.11-macos-aarch64-none (python3.12)

아래는 설치된 파이썬 리스트 조회입니다.

# 설치된 파이썬 리스트 조회
uv python list                                                                                                                    ✔  20:15:21
cpython-3.14.0rc1-macos-aarch64-none                 <download available>
cpython-3.14.0rc1+freethreaded-macos-aarch64-none    <download available>
cpython-3.13.6-macos-aarch64-none                    <download available>
cpython-3.13.6+freethreaded-macos-aarch64-none       <download available>
cpython-3.12.11-macos-aarch64-none                   .pyenv/shims/python3.12
cpython-3.12.11-macos-aarch64-none                   .pyenv/shims/python3
cpython-3.12.11-macos-aarch64-none                   .pyenv/shims/python
cpython-3.12.11-macos-aarch64-none                   <download available>
cpython-3.11.13-macos-aarch64-none                   <download available>
cpython-3.10.18-macos-aarch64-none                   <download available>
cpython-3.9.23-macos-aarch64-none                    <download available>
cpython-3.9.6-macos-aarch64-none                     /usr/bin/python3
cpython-3.8.20-macos-aarch64-none                    <download available>
pypy-3.11.13-macos-aarch64-none                      <download available>
pypy-3.10.16-macos-aarch64-none                      <download available>
pypy-3.9.19-macos-aarch64-none                       <download available>
pypy-3.8.16-macos-aarch64-none                       <download available>
graalpy-3.11.0-macos-aarch64-none                    <download available>
graalpy-3.10.0-macos-aarch64-none                    <download available>
graalpy-3.8.5-macos-aarch64-none                     <download available>

만약 특정 버전의 파이썬을 제거하고 싶다면 다음과 같이 진행합니다.

uv python uninstall 3.10.18                                                                                                       ✔  20:14:48

Searching for Python versions matching: Python 3.10.18
Uninstalled Python 3.10.18 in 126ms
 - cpython-3.10.18-macos-aarch64-none

가상환경 세팅

uv를 활용하여 가상환경을 생성할 때 --python 인자값을 사용해 파이썬 버전을 지정할 수 있습니다.

uv venv       

Using CPython 3.12.11
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

# 특정 파이썬 버전 입력
uv venv --python 3.9

Using CPython 3.9.6 interpreter at: /Library/Developer/CommandLineTools/usr/bin/python3
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

프로젝트 생성 및 초기 파일 생성

uv init

# 또는 파이썬 버전 추가
uv init --no-workspace --python 3.12

# 가상환경 없이 프로젝트 생성
uv init my-project --no-venv

# 파일 생성
.gitignore
.python-version # 파이썬 버전 고정
main.py
pyproject.toml # 의존성 및. ㅡ로젝트 메타데이터 정의
README.md

만약 error: Failed to discover parent workspace; 가 발생했다면 --no-workspace 옵션을 추가합니다.

uv init --no-workspace

의존성 설치

uv add requests

Resolved 6 packages in 81ms
Prepared 5 packages in 71ms
Installed 5 packages in 3ms
 + certifi==2025.8.3
 + charset-normalizer==3.4.3
 + idna==3.10
 + requests==2.32.4
 + urllib3==2.5.0

위와 같이 설치하면 pyprojects.toml 파일 내 dependencies에 "requests>=2.32.4", 가 추가되며 uv.lock 파일이 생성됩니다.

# pyprojects.toml

[project]
name = "test2"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.32.4",
]

만약 pip install fastapi[standard]와 같이 선택적 종속성을 설치해야 된다면 —extra 옵션을 추가하도록 합니다.

# pip install fastapi[standard]와 동일
uv add fastapi --extra standard

개발 환경 또는 별도의 그룹에 의존성 추가

개발환경에서만 사용할 의존성을 추가하려면 —dev 옵션을 추가하도록 합니다.

uv add --dev ruff

Resolved 7 packages in 175ms
Prepared 1 package in 953ms
Installed 1 package in 2ms
 + ruff==0.12.9

# pyprojects.toml

[project]
name = "test2"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.32.4",
]

[dependency-groups]
dev = [
    "ruff>=0.12.9",
]

만약 dev가 아닌 ci라는 그룹에 설치를 하고자 하는 경우 다음과 같이 진행합니다.

uv add --group ci ruff

Resolved 7 packages in 61ms
Audited 6 packages in 0.05ms

[project]
name = "test2"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.32.4",
]

[dependency-groups]
ci = [
    "ruff>=0.12.9",
]
dev = [
    "ruff>=0.12.9",
]

requirements.txt 설치

uv add -r requirements.txt

의존성 동기화

uv add 명령어는 uv sync의 기능을 포함하고 있어서 패키지를 추가하면 자동으로 동기화까지 처리됩니다. 즉, 자동으로 uv sync를 실행하여 패키지를 설치하고 잠금 파일(uv.lock)을 업데이트합니다.

pyproject.toml에 직접 입력을 했다면 uv sync를 사용해 동기화 시켜야 합니다.

# 기본 의존성 설치 및 업데이트 (dependencies와 dependency-groups의 dev 설치)
uv sync

만약 개발만 동기화 하거나 개발을 제외하고 동기화 하거나 하고 싶은 경우, 아래와 같은 명령어를 입력합니다.

# dependencies만 싱크
uv sync --no-dev
# dependency-groups의 dev만 싱크
uv sync --only-dev
# 특정 그룹만 싱크 - dev가 존재하다면 dev는 필수적으로 설치됨
--group <GROUP>
# 특정 그룹만 싱크 제외
uv sync --no-group <NO_GROUP>

스크립트 실행

uv run을 입력하면 가상환경을 자동 적용하여 파이썬 스크립트를 실행합니다. 만약 패키지 설치가 안되었다고 하면 패키지를 설치한 후 실행합니다. 즉 uv run은 uv venv, uv sync를 포함하고 있습니다.

uv run <파일명>

임시 의존성 설치 후 실행

uvx 명령어를 사용하면 파이썬 패키지를 설치하지 않고 임시 환경에서 즉시 실행할 수 있습니다.

• 과거의 방식
  1. 전역 또는 가상 환경에 도구를 설치합니다. (pip install black)
  2. 명령어를 실행합니다. (black .)
  3. 환경을 오염시키지 않기 위해 다시 삭제합니다. (pip uninstall black)
• uvx 방식
  1. 격리된 임시 환경을 만듭니다. (uvx black .)
  2. black 패키지와 그 의존성을 다운로드하여 설치합니다.
  3. black . 명령어를 실행합니다.
  4. 명령 실행이 끝나면 만들었던 임시 환경과 패키지를 모두 폐기합니다.

uvx는 단일 패키지만 설치하고 사용하는 것이 목적에 맞습니다. 여러 패키지를 설치할 순 있지만 의도와 멀어지게 됩니다.

pyproject.toml 기반으로 requirements.txt 생성

—no-deps 옵션은 하위 의존성은 무시하고 requirements.txt에 입력합니다.

uv pip compile pyproject.toml -o requirements.txt --no-deps

만약 특정 그룹의 패키지도 설치하려면 —group <그룹명> 옵션을 추가하면 됩니다. 이 때, 기본 의존성은 필수로 입력됩니다.

 uv pip compile pyproject.toml -o dev_requirements.txt --no-deps --group dev