[Python] uv 프로젝트 관리

기존 python 생태계는 pip 와 requirements.txt 조합으로 패키지 의존성 관리를 해왔다. 나도 동일하게 pip, requirements.txt, venv 등을 사용해서 프로젝트 환경 관리, 패키지 관리 등을 했다.

 

이번에 새로운 프로젝트를 진행하면서 팀원의 제안으로 uv 도입을 검토하게 되었다. uv 는 더 빠른 속도의 패키지 관리를 넘어 프로젝트 전반적인 관리까지 다양한 기능을 제공해 준다고 한다.

 

이 글에서는 uv 가 무엇인지, 어떤 기능을 제공해주는지, 그리고 기존의 pip 와 어떤 차이가 있는지를 정리한다.

1. uv 란

uv 는 Rust 로 개발된 빠른 속도를 자랑하는 파이썬 패키지 및 프로젝트 관리 도구이다. 기본적인 파이썬 패키지 설치, 의존성 관리 등의 기능뿐 아니라 가상환경 관리, 파이썬 스크립트 / 명령어 실행까지 다양한 기능들을 제공해준다.

 

uv 의 장점으로 가장 먼저 나오는 것이 매우 빠른 속도이다. Rust 기반으로 구현되었으며 패키지 다운로드 및 설치의 병렬 처리, 전역 캐시, 고도화 된 resolver 등을 통해 속도가 매우 빠르다. 공식문서의 벤치마크에서는 pip 의 10배 ~ 100배까지도 빠르다고 한다.

 

기존에는 패키지 설치, 의존성 관리, 가상환경 생성, 프로젝트 메타데이터 관리 등을 위해서 각각의 도구들을 사용했어야 했다. pip, venv, requirements.txt, poetry, virtualenv 등이 있다. uv 는 이러한 도구들을 대체할 수 있는 종합 관리 도구이다.

 

기존의 도구들을 대체할 뿐 아니라 pip, venv 등에 대해서는 호환 인터페이스도 제공해준다. uv pip 명령어를 사용하면 기존 pip 와 requirements.txt 를 그대로 동작시킬 수 있다.

 

이외에도 다양한 기능들을 제공한다.

2. 기능

uv 는 파이썬 프로젝트에 대한 종합적인 관리를 제공해준다. 그만큼 다양한 기능이 있는데, 이 글에서는 프로젝트 파이썬 관리와 파이썬 패키지 의존성 관리 관련 기능들을 중심으로 정리했다.

- Python 관리

uv python install [OPTIONS] [TARGETS]

[TARGET] 으로 지정한 버전의 파이썬을 설치하는 명령어

uv python uninstall [OPTIONS] [REQUEST]

[REQUEST] 로 입력한 버전의 파이썬을 삭제하는 명령어

uv python list [OPTIONS] [REQUEST]

설치 가능한 파이썬 버전을 출력하는 명령어

[REQUEST] 에 특정 버전을 입력하면 해당 버전의 파이썬들만 출력된다.

 

$ uv python list 3.13
cpython-3.13.12-linux-aarch64-musl    /usr/local/bin/python3.13
cpython-3.13.12-linux-aarch64-musl    /usr/local/bin/python3 -> python3.13
cpython-3.13.12-linux-aarch64-musl    /usr/local/bin/python -> python3
cpython-3.13.12-linux-aarch64-musl    <download available>

 

따로 버전을 입력하지 않으면 아래와 같이 전체 버전의 파이썬이 출력된다.

 

$ uv python list
cpython-3.15.0a6-linux-aarch64-musl                 <download available>
cpython-3.15.0a6+freethreaded-linux-aarch64-musl    <download available>
cpython-3.14.3-linux-aarch64-musl                   /root/.local/share/uv/python/cpython-3.14-linux-aarch64-musl/bin/python3.14
cpython-3.14.3+freethreaded-linux-aarch64-musl      <download available>
cpython-3.13.12-linux-aarch64-musl                  /usr/local/bin/python3.13
...

uv python pin [OPTIONS] [REQUEST]

프로젝트에서 사용할 파이썬 버전을 지정하는 명령어

[REQUEST] 로 지정한 버전의 파이썬을 현재 프로젝트에서 사용할 파이썬 버전으로 지정한다.

 

pin 명령어를 사용하면 지정된 버전이 .python-version 파일에 저장된다.

- 파이썬 프로젝트 관리

uv init [OPTIONS] [PATH]

[PATH] 에 지정된 경로에 새로운 파이썬 프로젝트를 생성하는 명령어.

프로젝트 디렉토리 아래에 .python-version, README.md, pyproject.toml, main.py 등 파일이 기본적으로 생성된다.

 

새로 생성된 프로젝트에서 처음으로 uv 실행 명령어 (uv run, uv sync, uv lock 등) 을 실행하면 프로젝트  환경 관리를 위해 가상환경 .venv 와 uv.lock 파일이 프로젝트 루트에 생성된다.

 

- pyproject.toml: 프로젝트 메타 데이터를 저장하고 있는 파일. 프로젝트 의존성뿐만 아니라 프로젝트 설명, 라이센스 등의 세부정보를 지정하는데 사용된다. 직접 수정할 수도 있고, uv add 나 uv remove 와 같은 명령어로 관리할 수도 있다.

- .python-version: 프로젝트의 기본 파이썬 버전을 저장한 파일. 프로젝트의 가상환경을 생성할 때 사용할 파이썬 버전을 알려준다.

- .venv: 프로젝트의 파이썬 가상환경

- uv.lock: 프로젝트 의존성 정보를 가지고 있는 크로스 플랫폼 lockfile. 프로젝트의 전반적인 내용이 포함된 pyproject.toml 과달리 정확하게 프로젝트 환경에 설치된 버전만 포함한다. 수동으로 수정하면 안되고 uv 를 통해서만 관리되야 하며, 버전 관리를 통해서 다른 환경에서도 프로젝트 환경을 재현될 수 있도록 관리해야 한다.

uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>

파이썬 패키지 의존성을 추가하는 명령어

실행하면 아래와 같이 지정한 패키지와 의존 관계에 있는 패키지들을 설치한다.

 

$ uv add requests
Resolved 6 packages in 647ms
Prepared 5 packages in 698ms
░░░░░░░░░░░░░░░░░░░░ [0/5] Installing wheels...                                                                                                                               warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
         If the cache and target directories are on different filesystems, hardlinking may not be supported.
         If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.
Installed 5 packages in 187ms
 + certifi==2026.1.4
 + charset-normalizer==3.4.4
 + idna==3.11
 + requests==2.32.5
 + urllib3==2.6.3

 

설치가 완료되면 uv.lock 과 pyproject.toml 의 내용이 설치된 의존성 정보를 기반으로 업데이트 된다.

uv remove [OPTIONS] <PACKAGES>...

프로젝트에 설치된 패키지 의존성을 삭제하는 명령어

명령어를 실행하면 아래와 같이 의존성이 삭제되고 uv.lock 과 pyproject.toml 에서도 관련 정보가 삭제된다.

 

$ uv remove requests
Resolved 1 package in 9ms
Uninstalled 5 packages in 80ms
 - certifi==2026.1.4
 - charset-normalizer==3.4.4
 - idna==3.11
 - requests==2.32.5
 - urllib3==2.6.

uv sync [OPTIONS]

프로젝트 의존성을 동기화시켜 프로젝트 환경을 업데이트 하는 명령어

uv lock 파일 기반으로 의존성을 설치한다.

uv lock [OPTIONS]

프로젝트의 lock 파일을 프로젝트 환경에 맞춰 생성한다.

pip freeze 와 같은 기능으로 이미 lock 파일이 있는 경우 환경에 맞춰 내용을 업데이트한다.

uv run [OPTIONS] [COMMAND]

프로젝트 환경의 명령어나 파이썬 스크립트를 실행한다.

uv run main.py 나 uv run ruff check 등과 같이 파이썬 패키지 명령어를 실행할 때 사용한다.

uv tree [OPTIONS]

프로젝트의 의존성 트리를 출력하는 명령어

실행하면 아래와 같이 패키지 의존성이 트리 형식으로 출력된다.

 

$ uv tree
Resolved 6 packages in 5ms
example v0.1.0
└── requests v2.32.5
    ├── certifi v2026.1.4
    ├── charset-normalizer v3.4.4
    ├── idna v3.11
    └── urllib3 v2.6.3

uv build [OPTIONS] [SRC]

[SRC] 로 지정된 디렉토리의 소스코드를 source distribution (tar.gz) 과 whl 파일로 빌드한다.

[SRC] 경로를 따로 지정하지 않으면 현재 위치를 [SRC] 로 빌드가 진행된다.

빌드된 산출물은 dist 디렉토리 아래에 저장된다.

uv publish [OPTIONS] [FILES]...

빌트된 프로젝트 아카이브를 패키지 저장소에 배포하는 명령어

- 그 외 기능들

PyPI 에 배포된 파이썬 패키지들의 설치 및 실행을 위한 uvx, uv tool 과 같은 기능들도 있다. uv tool 을 통해 패키지들을 설치, 업데이트 등을 수행한다.

 

uv 자체 기능뿐만 아니라 기존 pip 와 호환되는 uv pip 인터페이스도 제공해준다.

대표적으로 패키지 설치를 위한 uv pip install, 가상환경 구성을 위한 uv venv 등이 있다.

3. pip 와 비교

pip 와 uv 는 둘 다 파이썬 프로젝트의 관리를 위한 도구이지만 각자가 목표하는 바가 다르다는 느낌을 받았다.

 

pip 는 파이썬 패키지 설치, 의존성 관리에 집중한 도구라면, uv 는 패키지 관리 뿐만 아니라 프로젝트 전체 환경을 관리하기 위한 도구이다. lockfile, sync 등을 통한 파이썬 패키지 관리 뿐만 아니라 파이썬 설치 및 버전 관리, 가상환경 생성, 파이썬 스크립트 및 패키지 실행 등 다양한 기능을 제공한다.

 

패키지 관리에서도 보다 고도화 된 기능을 제공한다. 기본 pip 는 패키지 간의 내부 의존성으로 인한 이행적 종속성에 대한 관리를 명시적으로 안하는 경우가 있다. 이로 인해서 간접적으로 참조하는 패키지가 업데이트 된 경우 재설치시에 기존 환경과 의존성이 달라질 수 있다. 반면 uv 의 lockfile 은 이러한 의존성도 모두 고정하여 항상 동일한 환경을 재현할 수 있도록 한다.

 

이외에도 빠른 속도로 개발 환경, CI, 도커 이미지 빌드 등 프로젝트 크기가 커질 수록 더 유리한 장점이 있다. 기존 pip, requirements.txt 와도 호환되기 때문에 파이썬 개발을 하고 있다면 uv 도입을 한번 고려해보면 좋을 거 같다.

[References]

- https://docs.astral.sh/uv/

uv

- https://devocean.sk.com/blog/techBoardDetail.do?ID=167420&boardType=techBlog

PIP를 대체하는 UV 사용법 가이드