uv는 최근 등장한 차세대 파이썬 패키지 관리 도구로, pip, virtualenv, pipx, Poetry, pyenv 등 여러 툴의 기능을 하나로 통합한 것이 가장 큰 특징이다. Rust로 개발된 덕분에 속도가 매우 빠르며, 종전의 패키지 관리자들보다 10~100배까지 빠른 설치 속도를 보여준다. uv를 간략히 소개하고, 설치 방법과 기본 명령어들을 소개한다.

1. uv란 무엇인가?

uv는 Python 생태계에서 환경 및 패키지 관리를 혁신하기 위해 등장한 도구이다. 한 마디로 정리하면 “pip, 가상환경, Poetry, pyenv 등을 모두 합친 통합 도구”라고 할 수 있다. 기존에 파이썬 프로젝트를 관리하기 위해 pip, virtualenv, Poetry, pyenv, pipx 등의 여러 가지 도구를 조합하여 사용했는데, uv는 이 모든 작업을 단일 명령어 인터페이스에서 처리할 수 있도록 설계되었다. 즉, uv 하나만 배우면 패키지 설치, 의존성 해결, 가상환경 관리, 파이썬 버전 설치, 심지어 패키지 배포까지도 커버할 수 있다.

uv의 철학과 강점을 몇 보면 다음과 같다.

• 속도: uv는 Rust로 구현되어 패키지 설치와 의존성 해석이 매우 빠르다. 병렬 다운로드와 최적화된 의존성 해결 알고리즘 덕분에, uv는 pip 대비 10~100배 빠른 성능을 보여준다. 매우 빠르다.
• 기능 통합: uv 하나로 대부분의 패키지/환경 작업이 가능하므로 여러 도구를 번갈아 쓸 필요가 없다. 예를 들어 uv는 pip처럼 패키지를 설치, Poetry처럼 프로젝트별 lockfile 생성, uv run이나 uvx 명령을 통해 pipx 없이도 CLI 도구를 격리 실행이 가능하다.
• 사용 편의 및 호환성: uv는 기존 pip 인터페이스와 호환성이 높아 배우기 쉽고, 기존 워크플로우에 무리 없이 통합할 수 있다.
• 재현 가능한 환경: uv는 프로젝트마다 pyproject.toml 및 uv.lock 락파일을 사용하여 의존성의 정확한 버전과 해시를 고정한다. 이는 팀원 간 일관된 패키지 구성을 보장하여 환경 차이로 인한 오류 가능성을 없애준다.

정리하면, uv는 속도와 편의성 면에서 “미래의 파이썬 패키지 관리자”로 주목받는 도구이다.

2. uv 설치하기

uv는 현재 Windows, macOS, Linux 등 주요 운영체제를 모두 지원한다. 설치 방법은 OS별로 약간씩 다르며, macOS/Linux 기준으로 작성하였다.

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

위 명령은 Astral에서 제공하는 설치 스크립트를 내려받아 uv를 시스템에 설치한다.

Mac 사용자는 Homebrew 패키지 매니저를 통해 간단히 설치할 수도 있다.

$ brew install uv

uv는 PyPI에도 배포되어 있어 pip로 설치할 수도 있다​. 다만 이 경우 uv가 관리하는 가상환경 내에 설치되므로, 글로벌 툴로 사용하려면 pipx를 이용하는 것이 권장된다. (예: pipx install uv). 여튼 공식 문서에서는 독립 실행형(installer) 설치를 권장하니, 이 방식으로 설치한다.

3. uv를 활용한 프로젝트 관리

이제 uv를 실제 파이썬 프로젝트에 활용하는 방법을 수행해보자. 새로운 프로젝트를 uv로 시작하는 과정을 따라가 보겠다.

1. 프로젝트 생성

새로운 파이썬 프로젝트를 uv로 시작하려면, 원하는 디렉토리에서 uv init 명령을 실행한다. 예를 들어 myproject라는 새 프로젝트를 만들 때:

$ uv init myproject
Initialized project `myproject` at `~/myproject`

위 명령은 myproject 폴더를 생성하고 기본 설정 파일들을 만들어준다. pyproject.toml 파일에 프로젝트 이름(myproject)과 기본 버전(보통 0.1.0)이 설정되고, uv가 사용할 락파일(uv.lock)도 준비된다. 기존 Poetry의 poetry init과 유사하지만, uv는 기본값으로 최소한의 설정만을 수행한다.

2. 가상환경 구성

uv는 가상환경(virtual environment) 사용을 전제로 동작한다. uv init 자체는 가상환경을 바로 만들지 않지만, 이후 패키지를 추가할 때 자동으로 생성하게 된다. 만약 특정 Python 버전을 사용하는 가상환경을 바로 만들고 싶다면 uv venv 명령을 사용할 수 있다. 예를 들어 Python 3.13로 가상환경을 생성하려면:

$ uv venv --python 3.13
Using CPython 3.13.0
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

위와 같이 uv venv를 실행하면 현재 디렉토리에 .venv 폴더로 가상환경이 생성된다. –python 옵션으로 설치된 특정 파이썬 버전을 지정할 수 있고, 만약 지정한 버전이 없으면 uv가 알아서 다운로드까지 수행한다. 가상환경이 생성되면 “Activate with: …” 메시지가 나오는데, 수동으로 활성화하지 않더라도 uv 명령들은 내부적으로 이 .venv를 활용한다.

3. 의존성 추가 (uv add)

프로젝트에서 사용할 패키지를 설치하려면 uv add 패키지명 명령을 사용한다. 예를 들어 이 프로젝트에서 requests 패키지를 쓰고 싶다면:

$ uv add requests

처음 uv add를 실행하는 경우 uv는 자동으로 .venv 가상환경을 생성하고 패키지를 설치한다. 위 명령을 실행하면 requests와 그 의존 패키지들이 초고속으로 설치되며, pyproject.toml의 project dependencies 섹션에 “requests” 항목이 추가된다.

$ cat pyproject.toml
[project]
name = "myproject"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "requests>=2.32.3",
]

또한 현재 설치된 정확한 버전 정보가 uv.lock 락파일에 기록된다. uv는 add 시에 최신 호환 버전을 알아서 해석(resolution)하여 설치하므로, 추가로 pip install이나 pip freeze를 할 필요가 없다. 만약 복수의 패키지를 한 번에 추가하고 싶다면 공백으로 구분하여 uv add requests flask처럼 나열하면 설치된다.

4. 의존성 제거 (uv remove)

실수로 불필요한 패키지를 추가했거나 더 이상 사용하지 않는 패키지가 생겼다면 uv remove 패키지명으로 손쉽게 제거할 수 있다. 예를 들어 위에서 추가한 flask를 제거하려면

$ uv remove flask

이 명령을 실행하면 pyproject.toml에서 해당 패키지 명이 삭제되고, 가상환경에서도 패키지가 uninstall 된다. uv는 패키지 제거 시에도 의존성 관계를 분석하여, 더 이상 사용되지 않는 의존 패키지가 있다면 함께 정리해준다.

5. 환경 동기화 (uv sync)

uv sync 명령은 현재 pyproject.toml과 uv.lock에 명시된 내용과 실제 가상환경을 동기화한다. 보통 다음과 같은 상황에서 uv sync를 사용한다.

• git를 통해 협업 시, 다른 개발자가 업데이트한 의존성 변경사항을 받아온 경우 (이때 uv.lock이 바뀌었으므로 환경을 맞춰야 함).
• 수동으로 pyproject.toml이나 의존성을 수정한 경우 (예: 버전 범위 변경 등) 락파일을 재생성하고 설치를 적용해야 함.
• 프로젝트 초기 설정 후, uv add 대신 의존성을 직접 pyproject에 기재한 상황 등.

uv sync를 실행하면 필요한 패키지가 설치되고 불필요한 패키지는 제거되어 환경이 정의된 의존성과 일치하게 됩다. 쉽게 말해 Poetry의 poetry install과 유사한 동작을 uv에서 담당한다고 보면 된다. (참고로 uv lock 명령은 pyproject 기반으로 락파일만 갱신하며, uv sync는 그 락파일을 바탕으로 환경을 세팅한다.)

이상으로 새로운 프로젝트에서 uv를 사용하여 의존성을 추가/제거하고, 가상환경을 관리하는 기본 과정을 살펴보았다. uv를 사용하면 의존성 추가 시 자동으로 가상환경을 만들어주고, 락파일까지 관리해주므로 개발자는 필요한 패키지 이름만 추가하면 되는 단순한 워크플로우를 갖게 된다.

6. 프로젝트 관리 예시

다음은 신규 프로젝트 생성을 위한 예시 흐름이다.

$ uv init myproject -p ">=3.12"
$ uv env
$ source .venv/bin/activate
$ uv add click
$ python main.py

다음은 GIT repo를 다운로드한 프로젝트 관리를 위한 예시 흐름이다.

$ git clone TEST_GIT_REPO
$ uv sync
$ source .venv/bin/activate
$ python main.py

4. uv의 주요 명령어 익히기

uv에는 앞서 살펴본 것 외에도 다양한 명령어가 있다. 여기서는 자주 사용하는 기본 명령어들과 그 역할을 소개한다.

1. 새로운 프로젝트 초기화

– 새로운 프로젝트를 초기화한다. 현재 디렉토리에 pyproject.toml을 생성하고 기본 설정을 추가한다.

$ uv init # uv init은 현재 폴더를 프로젝트로 초기화

– 새로운 프로젝트를 초기화한다. myproject 디렉토리에 pyproject.toml을 생성하고 기본 설정을 추가한다.

$ uv init myproject # myproject 폴더를 생성하고 프로젝트로 초기화

– 지원할 python 버전을 지정하여 새로운 프로젝트를 초기화한다.

$ uv init -p "=3.10" myproject # 단일 버전
$ uv init -p ">=3.10" myproject # 최소 버전
$ uv init -p ">=3.10,<3.13" myproject # 버전 범위
$ uv init -p ">=3.10,!=3.9.5,<3.13" myproject # 여러 조건

2. 패키지를 추가

– 프로젝트에 의존성 패키지를 추가한다. 패키지명 뒤에 버전을 지정하면 해당 버전으로 설치한다.

$ uv add requests
$ uv add requests fastapi pandas

3. 패키지를 제거

– 프로젝트에서 패키지를 제거한다. pyproject의 dependencies 목록과 가상환경에서 해당 패키지를 삭제한다.

$ uv remove pandas

4. 가상환경 업데이트

– 락파일(uv.lock)에 맞추어 가상환경을 업데이트한다. 새로운 의존성을 설치하고 불필요한 것을 제거하여 환경을 동기화한다.

$ uv sync

4. 가상환경에서 실행

– 현재 프로젝트의 가상환경에서 임의의 명령을 실행한다.

$ uv run main.py

5. Python 버전 다운로드

– 지정한 Python 인터프리터 버전을 다운로드하여 관리한다. 예를 들어 uv python install 3.11.5를 하면 CPython 3.11.5 버전이 시스템에 설치되고 uv에서 사용 가능해진다. 설치된 파이썬은 uv의 관리 하에 있으므로, 삭제나 목록 확인도 uv로 가능하다.

$ uv python install 3.11

6. Python 버전 목록

– uv로 설치한 Python 버전들을 정보와 함께 보여준다.

$ uv python list

7. 사용할 Python 버전 고정

– 현재 프로젝트에서 사용할 Python 버전을 고정한다. 이 기능은 pyenv의 .python-version과 유사하며, 프로젝트별 Python 버전을 쉽게 전환할 수 있게 해준다.

$ uv python pin 3.11

8. 전역 툴 설치

– 전역적으로 사용할 CLI 툴을 설치한다. 예를 들어 uv tool install ruff를 하면 파이썬 린터 ruff가 설치되고, 명령어 ruff를 바로 사용할 수 있게 링크해준다. 이는 pipx install과 유사한 기능으로, 설치된 툴은 시스템 어디에서나 호출 가능하다. uv tool list로 설치된 툴 목록을 볼 수도 있다.

$ uv tool install ruff

9. 임시 가상환경에서 실행

– 임시 가상환경에서 CLI 툴을 실행하는 명령어다. uvx는 uv tool run의 별칭(alias)으로, 지정한 파이썬 패키지의 커맨드를 바로 실행해준다. 예를 들어 한 번만 쓸 스크립트가 필요할 때 uvx cowsay “Hello”를 실행하면, pycowsay 패키지가 임시로 설치된 후 곧바로 해당 명령이 실행되고 결과를 출력한다. 매번 새로운 격리 환경에서 실행하므로 전역 환경을 더럽히지 않는다. 설치되지 않은 툴도 자동 설치하여 실행해주고, 이후 캐시되므로 재실행도 빠르다.

$ uvx cossay -t "Hello"

위에 열거된 핵심 명령들만 이해하고 있어도 uv를 활용하는 데 큰 문제는 없다. 특히 Python 버전 관리와 uvx를 통한 CLI 실행 기능은 uv만의 강점이므로 꼭 한 번 사용해보길 추천한다. 그리고 추가 자세한 정보는 https://docs.astral.sh/uv를 참고하자.