uv : 엄청 빠르고 편리한 Python 프로젝트, 패키지 관리 프로그램

 

 

기존에 알고 있었던 pyenv, poetry, pip, venv 등은 잊어주세요. 이제는 uv 만 알고 있으면 Python 프로젝트 진행하는데 충분합니다. uv 는 Python 프로젝트와 패키지를 아주 쉽고 빠르게 관리해주는 툴입니다. 공식 사이트는 https://docs.astral.sh/uv/ 입니다.

uv의 주요 특징 및 장점

• 압도적인 속도: pip보다 10~100배 더 빠릅니다.
• 통합된 도구: pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv 등의 여러 도구를 하나의 uv로 대체할 수 있습니다.
• Cargo 스타일의 작업 공간 지원: 대규모 프로젝트에서 확장 가능한 프로젝트 관리를 용이하게 합니다.
• 디스크 공간 효율성: 전역 캐시를 사용하여 종속성을 중복 제거합니다.
• 간편한 설치: Rust나 Python 설치 없이 curl 또는 pip를 통해 설치할 수 있습니다.
• 다양한 플랫폼 지원: macOS, Linux, Windows를 지원합니다.
• 기존 워크플로우와의 호환성: 기존 pip, pip-tools, virtualenv 명령어를 대체하여 사용할 수 있어 마이그레이션이 용이합니다.
• 표준 준수: PEP 517, PEP 518, PEP 508, PEP 660 등 Python 표준을 완벽하게 지원합니다.
• 가상 환경 관리: uv venv 명령어를 통해 Python 버전을 지정하여 가상 환경을 생성하고 관리할 수 있습니다.
• Python 버전 관리: uv python install 명령어를 통해 필요한 Python 버전을 쉽게 설치하고 관리할 수 있습니다.
• 종속성 관리: uv add, uv remove 명령어를 사용하여 패키지를 추가하고 제거하며, 개발용 종속성 및 extra 종속성 관리도 지원합니다.
• lock 파일 및 requirements.txt 지원: uv export -o requirements.txt 명령어를 통해 requirements.txt 파일을 생성하고, uv.lock 파일을 통해 재현 가능한 빌드를 보장합니다.
• 스크립트 실행: uv run 명령어를 통해 가상 환경을 활성화하지 않고도 Python 스크립트를 실행할 수 있습니다.
• 도구 실행: uv tool run (또는 uvx) 명령어를 통해 Python 패키지에서 제공하는 명령줄 도구를 실행할 수 있습니다.

uv 설치

일단 빠르게 설치부터 해봅시다.

윈도우

$ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Mac/Liuux

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

uv 로 프로젝트 생성

uv 는 파이썬 프로젝트 관리도구에요. 다음과 같이 파이썬 프로젝트를 생성할 수 있어요.

$ uv init example

example 폴더 안에는 다음과 같은 파일들이 만들어집니다.

• .gitignore : 다들 아시다시피 git으로 관리하지 않을 파일을 지정합니다.
• .python-version : 이 프로젝트에서 사용할 파이썬의 버전이 명시되어 있어요. 가장 최신 버전이 설정되어 있어요. 필요하다면 다른 버전으로 바꾸어도 됩니다.
• main.py : 간단한 예제 프로그램이 들어 있어요. 실질적으로 여기에 작업을 해야겠지요.
• pyproject.toml : 이 파일이 중요합니다. node.js 로 보면, package.json 에 해당이 되요. 필요한 파이썬 버전이 명시되어 있고, 패키지에 대한 의존성 관리를 할 수 있어요.
• README.md : 이 프로젝트에 대한 설명을 적어 넣으시면 됩니다.

프로젝트 실행

example 폴더로 들어가서 uv run main.py 를 실행합니다.

C:\work\example> uv run .\main.py
Using CPython 3.13.3
Creating virtual environment at: .venv
Hello from example!
C:\work\example>

실행이 잘 됩니다. 그런데, 1~2번째 줄을 좀 봅시다. 이렇게 되어 있어요.

Using CPython 3.13.3
Creating virtual environment at: .venv

프로그램을 실행하자마자, CPython 3.13.3 이 설치가 되고, .venv 폴더를 생성해서 가상환경을 만들고, 바로 그 가상환경에서 main.py 를 실행하는 것을 보여줍니다. 다시, dir을 해보면, .venv 폴더가 생긴 것을 확인할 수 있어요.

PS C:\work\example> dir

    디렉터리: C:\work\example

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----      2025-04-16   오전 8:49                .venv
-a----      2025-04-15   오후 5:23            109 .gitignore
-a----      2025-04-15   오후 5:23              5 .python-version
-a----      2025-04-15   오후 5:23             85 main.py
-a----      2025-04-15   오후 5:23            153 pyproject.toml
-a----      2025-04-15   오후 5:23              0 README.md
-a----      2025-04-16   오전 8:49            127 uv.lock

PS C:\work\example>

다시 한번, uv run main.py 을 해보면, 이미 파이썬을 설치하고. 가상환경을 만들어 놓았기 때문에, 그에 대한 메시지가 또 나오지는 않습니다.

C:\work\example> uv run .\main.py
Hello from example!
C:\work\example>

패키지 관리

패키지를 하나 설치해봅시다. requests 라는 패키지를 설치하려면, 원래는 pip install requests로 했었지요. 이제는 uv add requests 로 하시면 됩니다.

C:\work\example> uv add requests
Resolved 6 packages in 163ms
Installed 5 packages in 69ms
 + certifi==2025.1.31
 + charset-normalizer==3.4.1
 + idna==3.10
 + requests==2.32.3
 + urllib3==2.4.0
C:\work\example>

pyproject.toml 파일을 열어보면, 아래처럼 requests 패키지가 추가된 것을 확인할 수 있어요.

[project]
name = "example"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "requests>=2.32.3",
]

main.py 파일 열어서 아래와 같이 작성해봅니다.

import requests

def main():
    resp = requests.get("https://peps.python.org/api/peps.json")
    data = resp.json()
    print(data)


if __name__ == "__main__":
    main()

이 것을 실행하면 이렇습니다.

이런 식으로 개발하시면 됩니다. 배포도 아주 간단해집니다. 해당 서버에는 파이썬이 설치되어 있을 필요가 없고, uv 만 설치되어 있으면, 작성한 소스를 복사만 해서 실행하면, 알아서 파이썬과 패키지들을 다운로드/설치하고 바로 실행이 됩니다.

https://docs.astral.sh/uv/ 에 보면 더 많은 정보들이 있기는 한데, 오늘 설명한 내용만으로도 충분히 작업이 가능할 거에요. 이 외에 더 필요한 사항이 생기면 문서를 보시면 됩니다. 근데 별로 볼 일 없을거에요. ^^