> Let's use uv

🐍 Python 기반 프로젝트에서 패키지 관리자 uv 사용법을 정리해 효능을 영업하고 싶어 작성
프로젝트를 init해서 진행할 때 사용될 명령어들을 정말 간단히 정리
자세한 사용법은 uv 공식 문서를 참고하세요!!

0. 서론

• An extremely fast Python package and project manager, written in Rust.
• uv는 Python 패키지 관리자로, pip보다 빠르고 현대적인 대안

1. 명령어 정리

1.1. install uv & python version

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

uv python install 3.12 3.13

1.2. initialize project

uv init some_project --python 3.12

some_project 
├──.python-version
├── README.md
├── main.py
└── pyproject.toml

1.3. package management

[🌙]: uv와 pyproject.toml은 npm에서 package를 추가하는 것과 유사하게 작동되는 것과 같은 생각

1.3.1. uv add: 패키지 추가

uv add torch torchaudio torchvision
uv add -r requirements.txt

• pyproject.toml에 의존성을 추가 + 해당 내용이 반영된 uv.lock을 자동으로 갱신
• 가상환경도 즉시 동기화!

1.3.2. uv pip install: 가상환경에만 패키지 설치

uv pip install transformers

• uv pip install은 일반 pip install처럼 패키지를 가상환경에만 설치한다. 프로젝트 메타데이터(pyproject.toml, uv.lock)는 변경하지 않는다.
• pyproject.toml에 의존성이 추가되지 않으므로 만약 pyproject.toml에 의존성을 추가하려면 uv add 명령어를 사용해야 한다.
  • uv pip freeze > requirements.txt 및 uv pip install -r requirements.txt 명령어를 사용해도 되지만 모든 의존성 패키지들이 requirements.txt에 추가된다는 단점이 있다.

별 일 없으면 uv add 명령어를 사용하자 👍

1.3.3. uv lock: pyproject.toml기반으로 uv.lock 갱신, 패키지 설치⋅삭제 X

uv lock

• pyproject.toml기반으로 uv.lock 갱신, 패키지 설치⋅삭제 X

1.3.4. uv sync: 가상 환경을 uv.lock과 동일한 상태로 재설치

uv sync

• 해당 명령어를 실행하면 uv.lock이 최신인지 확인함 -> 최신이 아니면 자동으로 갱신(uv lock 명령어 실행)
• 기본적으로 uv.lock에 없는 패키지는 삭제하나 --inexact 옵션으로 삭제하지 않을 수 있다.
• --locked, --frozen, --no-sync 옵션으로 명령어 실행시 uv lock 명령어 건너뛰기 등을 확인 가능 (cf. uv docs - Automatic lock and sync)

uv sync 명령어를 더 사용하고 있습니다.

1.3.5. uv export: pyproject.toml 기반으로 requirements.txt 생성

uv export -o requirements.txt

• pyproject.toml 기반으로 requirements.txt 생성
• 가상환경에 설치된 모든 패키지를 추가하려면 uv pip freeze > requirements.txt 명령어를 사용

1.4. run python script

uv run train.py
uv run python train.py

1.5. Jupyter Notebook in vscode (cursor)

uv add jupyter ipykernel

1.5.1. 현재 VS Code의 워크스페이스 폴더(parent_folder)가 uv init된 폴더인 경우

• .ipynb 파일에서 [커널 선택] → [Python 환경 선택] → [.venv (./venv/bin/python)] 선택

1.5.2. [parent_folder] 안에 uv init sample-project로 생성한 하위 폴더가 있는 경우

• .ipynb 파일에서 [커널 선택] 메뉴에 .venv가 자동으로 표시된다면 그대로 진행하면 된다.
• 그러나 자동으로 표시되지 않는다면 .vscode/settings.json 없이 해결하는 방법이 존재한다.

1. [sample-project] 폴더를 VS Code에서 별도 워크스페이스로 연다.
2. [sample-project] 내 .ipynb 파일에서 [커널 선택] → [Python 환경 선택] → [.venv (./venv/bin/python)] 선택 → cell 실행해서 커널 작동 확인
3. 이후 [parent_folder]로 돌아가 [sample-project] 안의 .ipynb 파일을 열면, 해당 가상환경이 자동으로 선택된 것을 확인할 수 있다.

2. 마무리

2.1. Cheat sheet

2.1.1. 많이 사용하는 명령어 모음

uv init sample-project --python 3.12
uv add <some_package>
uv run <some_script>
uv sync

2.1.2. 프로젝트에 적용된 가상환경 활성화

source .venv/bin/activate

• 프로젝트 폴더 내의 .venv가 가상환경 폴더입니다

2.1.3. 파이썬 버전 바꾸는 법

1. .python-version 파일에서 써진 파이썬 버전 변경
2. uv sync 실행 -> 가상환경이 해당 파이썬 버전으로 자동 동기화(.venv 폴더 내의 파이썬 버전 변경됨)

2.2. Use 'asdf' for global python version management

• uv가 글로벌 파이썬 환경 설정이 매우 불편해서 asdf(asdf-vm)에서의 python plugin을 사용해서 사용하면 좋습니다.
• 사실 asdf가 nodejs, ruby 등 다양한 언어를 하나의 도구로 관리하는 것이라 여러 언어를 사용하는 경우 편리합니다.

[🌙]: 현재 웹 애플리케이션 개발에 nodejs, jekyll 개발을 위해 ruby, 그리고 글로벌 파이썬 환경 설정을 위해 python도 사용 중

#### === 대충 설치 진행 === ####
asdf plugin add python # python plugin 설치
asdf list python # 설치 가능한 python 버전 확인
asdf install python 3.12.9 # python 버전 설치
asdf set global python 3.12.9 # 글로벌로 설정