uv를 통한 Python 프로젝트 관리

Python 버전 관리, 의존성 관리, 가상환경 관리 등 통합 프로젝트 관리 도구인 uv를 사용하면 Python 프로젝트를 매우 쉽게 관리할 수 있다. 게다가 아래 표에서 확인할 수 있다시피 uv는 의존성 주입 등 환경 구성이 매우 빠르게 수행되는 장점이 있다.

설치¶

uv는 기본적으로 아래와 같은 명령어로 설치가 가능하다. 최신 설치 방법은 공식 문서를 참고하자.

Windows

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

uv python install {PYTHON_VERSION}

uv python uninstall {PYTHON_VERSION}

uv python list

uv python pin {PYTHON_VERSION}

Tip

Python 버전 형식은 공식 문서 참고

uv init

:: 프로젝트 이름 설정
uv init --name {PROJECT_NAME}

:: 프로젝트용 Python 버전 지정
uv init --p {PYTHON_VERSION}

uv init --python {PYTHON_VERSION}

Note

--name 옵션을 사용하지 않을 경우 현재 폴더 이름을 프로젝트 이름으로 사용한다.

Warning

프로젝트 이름과 동일한 패키지는 설치 되지 않고 프로젝트 이름 변경이 복잡하기 때문에, 프로젝트 이름 선택 시 주의해야한다.

uv add {PACKAGE_NAME}

uv remove {PACKAGE_NAME}

-- requirements.txt 파일의 의존성 패키지 목록을 설치 옵션

uv add -r requirements.txt

uv add --requirements requirements.txt

uv sync

uv lock

uv tree

uv pip tree

uv venv {VENV_NAME}

Note

uv는 uv init으로 프로젝트를 생성한 후 uv sync, uv add 등의 명령어 실행 시 자동으로 가상환경을 생성해준다. uv venv 명령어는 단순 실험 등이 필요할 때 빠르게 가상환경 만을 생성하기 위해 사용한다.

uv run {SCRIPT_NAME}

Tip

uv run 명령어는 스크립트 뿐만 아니라 패키지 어플리케이션도 실행할 수 있다. FastAPI를 예시로 들면 uv를 사용할 때와 사용하지 않을 때 개발용 APP 실행 명령어는 아래와 같이 달라진다.

fastapi dev src/main.py

uv run fastapi dev src/main.py

uv run --no-project {SCRIPT_NAME}

Warning

uv run 명령어를 프로젝트²에서 사용할 경우 uv는 스크립트를 실행하기 전에 현재 프로젝트를 설치한다. 현재 프로젝트를 설치하지 않고 단순히 스크립트만 실행하고 싶은 경우 --no-project 옵션을 사용해줘야 한다.

uv run --with jupyter jupyter lab

uv add --dev ipykernel

Note

VS Code로 ipynb 파일을 수정하려면 jupyter 커널이 필요하다.

uv build

uv pip freeze > requirements.txt