주요 기능

uv는 파이썬 개발에 필수적인 기능을 제공한다. 단순한 스크립트 작업부터 여러 파이썬 버전과 플랫폼을 지원하는 대규모 프로젝트 작업까지 다양한 상황에서 활용할 수 있다.

uv의 인터페이스는 독립적으로 사용하거나 함께 사용할 수 있는 여러 섹션으로 나눌 수 있다.

파이썬 버전 관리

파이썬 자체를 설치하고 관리하는 방법.

• uv python install: 파이썬 버전을 설치한다.
• uv python list: 사용 가능한 파이썬 버전을 확인한다.
• uv python find: 설치된 파이썬 버전을 찾는다.
• uv python pin: 현재 프로젝트가 특정 파이썬 버전을 사용하도록 고정한다.
• uv python uninstall: 파이썬 버전을 제거한다.

파이썬 설치 가이드(guide on installing Python)를 참고하여 시작한다.

스크립트 실행

독립 실행형 Python 스크립트(예: example.py)를 실행하는 방법을 알아본다.

• uv run: 스크립트를 실행한다.
• uv add --script: 스크립트에 의존성을 추가한다.
• uv remove --script: 스크립트에서 의존성을 제거한다.

시작하기 위해 스크립트 실행 가이드를 참고한다.

프로젝트

pyproject.toml을 사용해 Python 프로젝트를 생성하고 작업하는 방법을 다룬다.

• uv init: 새로운 Python 프로젝트를 생성한다.
• uv add: 프로젝트에 의존성을 추가한다.
• uv remove: 프로젝트에서 의존성을 제거한다.
• uv sync: 프로젝트의 의존성을 환경과 동기화한다.
• uv lock: 프로젝트의 의존성을 위한 lockfile을 생성한다.
• uv run: 프로젝트 환경에서 명령어를 실행한다.
• uv tree: 프로젝트의 의존성 트리를 확인한다.
• uv build: 프로젝트를 배포용 아카이브로 빌드한다.
• uv publish: 프로젝트를 패키지 인덱스에 게시한다.

시작하기 위해 프로젝트 가이드를 참고한다.

도구

Python 패키지 인덱스에 게시된 도구(예: ruff 또는 black)를 실행하고 설치한다.

• uvx / uv tool run: 임시 환경에서 도구를 실행한다.
• uv tool install: 도구를 사용자 전체에 설치한다.
• uv tool uninstall: 도구를 제거한다.
• uv tool list: 설치된 도구 목록을 확인한다.
• uv tool update-shell: 도구 실행 파일을 포함하도록 셸을 업데이트한다.

시작하려면 도구 가이드를 참고한다.

pip 인터페이스

레거시 워크플로우나 상위 레벨 커맨드로 충분한 제어를 할 수 없는 경우, 환경과 패키지를 수동으로 관리한다.

가상 환경 생성 (venv와 virtualenv를 대체):

• uv venv: 새로운 가상 환경을 생성한다.

자세한 내용은 환경 사용 문서를 참고한다.

환경 내 패키지 관리 (pip와 pipdeptree를 대체):

• uv pip install: 현재 환경에 패키지를 설치한다.
• uv pip show: 설치된 패키지의 상세 정보를 표시한다.
• uv pip freeze: 설치된 패키지와 버전 목록을 출력한다.
• uv pip check: 현재 환경의 패키지 호환성을 확인한다.
• uv pip list: 설치된 패키지 목록을 출력한다.
• uv pip uninstall: 패키지를 제거한다.
• uv pip tree: 환경의 의존성 트리를 확인한다.

자세한 내용은 패키지 관리 문서를 참고한다.

환경 내 패키지 잠금 (pip-tools를 대체):

• uv pip compile: 요구 사항을 lockfile로 컴파일한다.
• uv pip sync: 환경을 lockfile과 동기화한다.

자세한 내용은 환경 잠금 문서를 참고한다.

중요

이 커맨드들은 기반으로 하는 도구들의 인터페이스와 동작을 정확히 구현하지 않는다. 일반적인 워크플로우에서 벗어날수록 차이점을 더 자주 마주칠 수 있다. 자세한 내용은 pip 호환성 가이드를 참고한다.

유틸리티

uv의 상태를 관리하고 검사하기 위한 명령어들이다. 캐시, 저장소 디렉토리 관리, 자동 업데이트 등을 수행할 수 있다:

• uv cache clean: 캐시 항목을 제거한다.
• uv cache prune: 오래된 캐시 항목을 제거한다.
• uv cache dir: uv 캐시 디렉토리 경로를 표시한다.
• uv tool dir: uv 도구 디렉토리 경로를 표시한다.
• uv python dir: uv로 설치된 Python 버전의 경로를 표시한다.
• uv self update: uv를 최신 버전으로 업데이트한다.

다음 단계

각 기능에 대한 소개는 가이드를 참고한다. uv의 기능에 대한 심층적인 내용은 개념 페이지에서 확인할 수 있다. 문제가 발생하면 도움말 페이지에서 해결 방법을 찾아본다.