[uv] uv 처음 설치하기

[uv] uv 처음 설치하기

Python 패키지 설치, 가상환경 생성, 의존성 관리를 uv로 진행하는 방법 정리

- 사전 확인

현재 Python 경로와 버전 확인

python --version
which python

어떤 Python을 기준으로 가상환경이 잡히는지 확인할 때 같이 보면 편하다

- uv 설치

공식 문서 기준 설치 명령어

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

curl이 없다면 wget 사용

wget -qO- https://astral.sh/uv/install.sh | sh

기본적으로 ~/.local/bin 아래에 설치된다

- PATH 확인

설치 후 버전 확인

uv --version
which uv

command not found: uv가 출력되면 PATH에 ~/.local/bin 추가

zsh

export PATH="$HOME/.local/bin:$PATH"

source ~/.zshrc

uv --version

- uv 업데이트

standalone installer로 설치한 경우

uv self update

설치 스크립트를 다시 실행하는 방식으로 업데이트된다

업데이트 후 버전 확인

uv --version

- Python 확인

uv에서 인식하는 Python 목록 확인

uv python list

목록에 있는 Python 설치

uv python install 3.12

특정 패치 버전 지정

uv python install 3.12.3

여러 버전 한 번에 설치

uv python install 3.11 3.12

설치 후 다시 확인

uv python list

특정 버전으로 가상환경 생성

uv venv --python 3.11

현재 Python 기준으로 생성

uv venv

기본 가상환경 경로는 .venv

- 기본 사용

프로젝트 초기화

mkdir uv-test
cd uv-test
uv init

패키지 추가

uv add requests

실행

uv run python -c "import requests; print(requests.__version__)"

uv add 실행 시 가상환경 생성, 의존성 설치, pyproject.toml 갱신, lock 파일 생성이 같이 진행된다

- 기본 흐름

1. 가상환경 생성

uv venv

2. 의존성 추가

uv add numpy pandas

3. 실행

uv run python main.py

프로젝트 기준으로 uv venv, uv add, uv run 흐름으로 사용하면 된다

- ipynb 파일 사용할 때

VS Code에서 ipynb 파일만 사용할 경우 ipykernel 설치

uv add --dev ipykernel

현재 가상환경을 커널로 등록

uv run python -m ipykernel install --user --name uv-project

VS Code에서 ipynb 파일을 열고 uv-project 커널 선택

보통은 여기까지만 해두면 된다
커널 이름은 프로젝트 이름에 맞게 변경해도 된다

- 선택 사항: 자동완성

zsh 자동완성 설정

echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
source ~/.zshrc

- 자주 쓰는 명령어

uv --version        # uv 버전 확인
uv python list      # 사용 가능한 Python 목록 확인
uv venv             # 가상환경 생성
uv add requests     # 패키지 추가
uv run python       # 가상환경 기준으로 Python 실행
uv sync             # lock 파일 기준으로 의존성 동기화

- 참고

• uv 공식 문서 - Installation
• uv 공식 문서 - First steps
• uv 공식 문서 - Installing and managing Python
• uv 공식 문서 - Python versions