uv 간단 사용법

1. uv란?

uv는 Astral에서 개발(2024년에 공개)한 Rust 기반의 Python package and project manager.

 

기존 Python 개발에서 따로 사용하던 여러 도구의 기능을 하나의 CLI로 통합하여 제공함.

다음의 기능들을 지원 기능:

• Python version management
• virtual environment 관리
• dependency resolution
• package installation
• lock file 생성
• project 실행
• CLI tool 실행

기존의 다음 도구들을 상당 부분 대체할 수 있는 형태를 목표로 함.

• pip
• venv
• pip-tools
• pipx
• pyenv

공식 문서: https://docs.astral.sh/uv/

소스 코드: https://github.com/astral-sh/uv

Python의 PyPI와 동일한 package index를 사용할 수 있다는 장점이 있음.
Python package는 uv로 관리하고,
기타 native dependency나 non-Python package는
conda로 관리하는 방식을 개인적으로 선호.

 

uv는 대략 다음과 같은 interface/workflow로 나누어 볼 수 있음:

• project : pyproject.toml 과 uv.lock 을 기준으로 project 자체를 관리하는 uv-native workflow.
• pip     : 현재 environment를 pip처럼 관리하는 pip-compatible interface.
• tool    : CLI tool을 project와 분리된 독립 환경에서 설치하고 실행하는 interface.
  • uvx 가 바로 uv tool run 의 alias임.
• script  : 단일 script의 실행 환경을 관리하는 workflow.
  • 단, 별도의 top-level 명령어가 아니라 uv run, uv add --script, uv remove --script 등을 통해 사용.
• python  : Python version 자체를 설치, 조회, 고정하는 interface.

---

2. uv 설치

Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

 

macOS

brew install uv

 

Windows

winget install --id=astral-sh.uv -e

 

설치 확인:

uv --version

---

3. 새 프로젝트 만들기

uv init myproj
cd myproj

 

생성되는 주요 파일은 다음과 같음.

myproj/
├── .python-version
├── main.py
├── pyproject.toml
└── README.md

 

여기서 pyproject.toml은 프로젝트 이름, Python 버전 조건, dependency 정보를 저장하는 파일임.

 

2026.05.04 - [Python] - uv 를 통한 wheel 빌드하기-uv_build, hatchling

uv 를 통한 wheel 빌드하기-uv_build, hatchling

---

4. Python 버전 지정

Python 3.12를 사용하려면 다음처럼 설치함.

uv python install 3.12

현재 프로젝트에서 사용할 Python 버전을 고정함.

uv python pin 3.12

 

이 명령은 .python-version 파일을 생성.

.python-version

 

이후 현재 프로젝트에서 uv run, uv sync, uv venv 등을 실행하면 이 파일에 설정된 버전을 우선 사용함.

 

다음으로 확인 가능:

uv run python --version

---

5. 프로그램 실행

기본 생성된 main.py를 실행함.

uv run main.py

 

또는 다음처럼 실행할 수 있음.

uv run python main.py

 

uv run은 해당 프로젝트의 가상환경(.venv)을 기준으로 명령을 실행함.

---

6. 패키지 설치

예를 들어 requests를 설치하려면 다음처럼 입력함.

uv add requests

 

설치 후 pyproject.toml에 dependency가 추가됨.

dependencies = [
    "requests>=...",
]

 

다음으로 버전 지정 등이 가능함

목적	명령
최신 version 추가	uv add requests
정확한 version 추가	uv add "requests==2.32.3"
최소 version 지정	uv add "requests>=2.32"
범위 지정	uv add "requests>=2.32,<3"
compatible release	uv add "requests~=2.32"
extra 포함	uv add "requests[socks]"

 

또한 uv.lock도 함께 갱신됨.

uv.lock

 

uv.lock은 실제로 어떤 버전의 패키지들이 설치되었는지를 기록하는 lock file임

(uv sync에서 사용됨).

---

7. 설치한 패키지 사용

main.py를 다음처럼 수정함.

import requests

response = requests.get("https://example.com")

print(response.status_code)
print(response.text[:200])

 

실행:

uv run main.py

---

8. 개발용 패키지 설치

개발(development) 과정에서만 필요한 테스트 도구(test tool), 포매터(formatter), 린터(linter) 등은 --dev 옵션으로 설치함.

uv add --dev pytest ruff

실행:

uv run pytest
uv run ruff check .

일반 dependency와 개발용 dependency를 구분할 수 있음.

---

9. 프로젝트 환경 복원

다른 컴퓨터에서 프로젝트를 받은 경우:

git clone <repo-url>
cd myproj
uv sync

uv sync는 pyproject.toml과 uv.lock을 기준으로 .venv를 구성함.

즉, 새 컴퓨터에서도 같은 패키지 버전으로 환경을 재현할 수 있음.

---

10. 격리된 가상환경 내 동작

보통은 uv run을 사용하면 격리된 가상환경 .venv에서 동작.

 

그래도 직접 활성화하려면 다음처럼 함.

 

macOS / Linux

source .venv/bin/activate

 

Windows PowerShell

.venv\Scripts\Activate.ps1

 

Windows cmd prompt

.venv\Scripts\activate.bat

 

비활성화:

deactivate

 

활성화 후에는 다음처럼 실행할 수 있음:

python main.py

 

하지만 uv 중심으로 사용할 때는 다음 방식이 더 명확하므로 개인적으로 권장함:

uv run main.py

---

11. 설치된 dependency 확인

uv tree

다음과 같은 형태로 현재 프로젝트의 dependency tree를 보여줌.

requests
├── certifi
├── charset-normalizer
├── idna
└── urllib3

---

12. 패키지 제거

uv remove requests

• pyproject.toml과 uv.lock에서 해당 dependency가 제거됨.
• 현재 프로젝트 내 가상환경인 .venv에서도 제거됨.

---

13. Python 목록 확인

uv python list

이 명령은 uv가 알고 있는 Python 목록을 보여줌.

여기에는 다음이 포함될 수 있음:

• uv가 직접 설치한 Python
• 시스템에 이미 설치된 Python
• PATH에서 발견되는 Python
• Windows py launcher로 찾을 수 있는 Python
• conda 환경의 Python
• 다운로드 가능한 Python

uv가 현재 프로젝트에서 실제로 사용할 Python 실행 파일의 경로를 보여주는 명령은 다음과 같음:

uv python find

• 다시 말해, uv run python으로 실행할 때 uv가 호출하는 Python이 어느 경로에 있는지를 확인할 수 있음.

특정 버전을 찾으려면:

uv python find 3.12

---

14. 일회성 CLI tool 실행

uvx는 Python package로 제공되는 CLI tool을 프로젝트에 dependency로 추가하지 않고 실행하는 명령임.

uvx는 uv tool run의 alias임

참고로, ruff는 Python용 Linter임.

• 역할: Python 코드의 문법, 스타일, 포맷, 코드 품질을 검사함
• 목적: flake8, pylint, pycodestyle 같은 기존 Python linter를 대체하거나 보완
• 특징:
  • 매우 빠름, Rust로 작성되어 속도가 빠름
  • 여러 lint 규칙(rule)을 기본 제공
  • --fix 옵션으로 일부 자동 수정 가능
  • uvx ruff check . 또는 프로젝트에 설치 후 uv run ruff check .로 실행 가능

2024.02.03 - [개발환경] - [linter] Linter (or Lint)

[linter] Linter (or Lint)

 

예를 들어 ruff를 프로젝트에 설치하지 않고(=영향을 주지않고) 실행하려면 다음처럼 사용함.

uvx ruff check .

• uvx는 내부적으로 해당 CLI tool과 필요한 dependency를 별도의 임시 environment에 준비한 뒤 실행함.
• 이때 생성된 environment와 dependency는 uv cache에 저장 되므로,
• 같은 tool을 다시 실행할 때 보통 매번 새로 다운로드하지 않음.

cache 위치는 다음 명령으로 확인할 수 있음.

uv cache dir

 

다만 다음 경우에는 다시 다운로드하거나 environment를 다시 만들 수 있음.

• uv cache clean 등으로 cache를 삭제한 경우
• cache에 해당 version의 tool이 없는 경우
• 다른 Python version, platform, dependency 조건이 필요한 경우

---

15. CLI tool(도구) 설치

자주 사용하는 CLI tool은 uvx로 매번 실행하기보다 uv tool install로 설치해서 사용하는 것이 적절함.

uvx tool install도
Python package 형태로 배포되는
CLI tool을 대상으로 함.

uvx와 uv tool install의 차이는 다음과 같음.

구분	uvx	uv tool install
목적	CLI tool을 임시 실행	CLI tool을 설치해서 계속 사용
설치 위치	uv cache 기반 임시 environment	uv가 관리하는 tool environment
프로젝트 dependency 추가	추가하지 않음	추가하지 않음
실행 방식	uvx ruff check .	ruff check .
적합한 경우	가끔 사용하는 tool	자주 사용하는 tool
예	uvx pycowsay hello	uv tool install ruff

 

즉, uvx는 일회성 실행용이고, uv tool install은 반복 사용을 위한 설치용임.

• uv tool install의 경우 현재 프로젝트의 .venv에 설치되는 것이 아니라,
• uv가 관리하는 별도의 tool environment에 설치하고,
• 실행 파일을 PATH에서 찾을 수 있는 위치에 연결
• 때문에 실행 파일은 uv의 tool executable directory에 연결됨.
• 따라서 특정 프로젝트 안에서 설치했더라도, 기본적으로는 사용자 계정 기준으로 사용할 수 있는 CLI tool이 됨

uv tool run 은
일회성 실행.

 

자주 사용하는 CLI tool은 다음처럼 설치해서 사용하는 것이 적절함.

uv tool install ruff

설치 후에는 다음처럼 바로 실행할 수 있음.

ruff check .

제거하려면 다음 명령을 사용함.

uv tool uninstall ruff

 

이 기능은 pipx와 비슷한 용도로 사용할 수 있음.

• pipx run ruff check . ≈ uvx ruff check .
• pipx install ruff ≈ uv tool install ruff

---

16. pip 방식으로 사용하기

기존 pip 스타일이 필요하면 uv pip를 사용할 수 있음.

 

가상환경 생성:

uv venv

 

패키지 설치:

uv pip install requests

 

설치된 패키지 목록 확인:

uv pip freeze

 

주의할 점은 uv pip 는 conda 환경과 uv를 같이 사용하는 경우 conda 환경에 패키지를 설치함(반면, uv add는 .venv에 설치).

 

uv pip 는 pip (or python -m pip) 와 마찬가지로 conda 환경을 우선시하므로 주의해야함.

(conda intall의 경우 요구되는 native runtime을 설치하는 것과 달리, pip 와 uv pip, uv add 모두 python wheel 형식의 패키지만 설치 가능하므로 과학계산 프로젝트 등과 같이 native runtime을 복잡하게 요구하는 경우에는 conda install 이 보다 편할 수 있음)

 

단, 새 프로젝트를 관리할 때는 보통 다음 흐름이 더 적절함.

uv init
uv add
uv run
uv sync

---

17. 간단 예제

새 프로젝트를 만든 뒤 패키지를 설치하고 실행하는 예제임:

17-1. project 생성

uv init myproj
cd myproj

• myproj directory가 생성되고, 그 안으로 이동함.

생성되는 주요 파일은 다음과 같음:

• main.py
• pyproject.toml
• README.md

---

17-2. Python version 지정

uv python install 3.12
uv python pin 3.12

• uv python install 3.12는 Python 3.12를 설치함 (기존에 설치된 경우엔 재설치 안해도 됨).
• uv python pin 3.12는 현재 project에서 사용할 Python version을 .python-version 파일에 기록함.

실제로 어느 Python 실행 파일을 사용하는지는 다음으로 확인가능:

uv python find

보통은 아래 명령어로 버전이 제대로 지정되었는지 확인:

uv run python --version

---

17-3. package 설치

uv add requests

• requests가 project dependency로 추가됨.

이때 다음 파일이 갱신됨.

• pyproject.toml
• uv.lock

또한 .venv에 실제 package가 설치됨.

---

17-4. code 작성

main.py를 다음처럼 수정함.

import requests

response = requests.get("https://example.com")

print(response.status_code)

---

17-5. 실행

uv run main.py

• uv run은 현재 project의 .venv를 사용해 code를 실행함.

---

17-6. 전체 흐름

uv init myproj
cd myproj

uv python install 3.12
uv python pin 3.12

uv add requests

uv run main.py

---

18. 핵심 명령어 정리

목적	명령어
프로젝트 생성	uv init myproj
Python 설치	uv python install 3.12
Python 버전 고정	uv python pin 3.12
Python 목록 확인	uv python list
사용할 Python 확인	uv python find
패키지 설치	uv add requests
개발용 패키지 설치	uv add --dev pytest
프로그램 실행	uv run main.py
환경 복원	uv sync
dependency tree 확인	uv tree
패키지 제거	uv remove requests
일회성 CLI 실행	uvx ruff check .
CLI 도구 설치	uv tool install ruff
pip 방식 설치	uv pip install requests

 

---

요약

uv에서 가장 많이 쓰는 명령은 다음 네 개임.

uv init
uv add
uv run
uv sync

 

Python 버전까지 같이 관리하려면 다음 명령을 추가로 사용함.

uv python install
uv python pin

 

즉, 일반적인 프로젝트 작업에서는 다음 정도만 익히면 충분함.

uv init myproj
cd myproj
uv python pin 3.12
uv add requests
uv run main.py