- 1. 설치 및 프로젝트 초기화
- 2. 의존성 관리: 설치와 기록을 동시에
- 3. 파이썬 버전 관리: 시스템 파이썬 건드리지 마라
- 4. Docker 배포: 빌드 속도 10배 빠르게
- 5. 요약: 이것만 기억하자
uv가 파이썬 생태계의 대통령이 된 이유는 딱 두 가지이다. “압도적인 속도” 와 “통합(Unification)”
(1) Rust로 짠 괴물 같은 속도
- 기존 (
pip,poetry): Python으로 만들어짐. 개느림. 의존성 그래프 계산하다가 퇴근 시간 다 간다.- 의존성: transformer 는 2.0 필요하고 근데 그와중에 numpy는 1.2 이하 필요하고, 그와중에 accelerate는 33 이상필요하고 ~~
- UV:
Rust로 만들어짐.pip보다 10~100배 빠름. 캐싱 전략이 미쳐서, 한 번 받은 패키지는 파일 복사도 안 하고 하드링크(Hardlink)로 꽂아버림. 디스크 용량도 아끼고 설치는 0.1초 컷.
(2) The Unified Toolchain (하나로 다 된다)
pyenv, conda(파이썬 버전 관리) ->uv pythonvenv, virtualenv(가상환경 생성) ->uv venvpip(패키지 설치) ->uv pippoetry, pip-tools(의존성 잠금/관리) ->uv add, uv lock
conda 만 써온사람으로써 일단 존나 무거움, 게다가 pycharm local<->remote<->container or cluster 개발 할 때 uv 못쓰고, .venv로 우회해야함.
1. 설치 및 프로젝트 초기화
UV 설치
# Mac/Linux (대장님 서버 포함)
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env
# 설치 확인
uv --version
프로젝트 시작하기 (uv init)
# 1. 프로젝트 폴더 생성
mkdir uv_test
cd uv_test
# 2. UV 프로젝트로 초기화 (여기서 파일들이 생성됨)
uv init
# 생성되는거
~/python_project/uv_test | main ?5 tree . ok | base py | 06:17:03
.
├── main.py
├── pyproject.toml
└── README.md
pyproject.toml (생성됨):
- 프로젝트의 명세서. 이름, 버전, 필요한 라이브러리 목록이 여기에 적힘.
- requirements.txt의 상위 호환 버전.
.python-version (생성됨):
- 현재 내 컴퓨터에 깔린 파이썬 버전(예: 3.12.1)이 기본으로 적혀서 생성됨.
- uv는 이 파일을 보고 어떤 파이썬을 쓸지 결정함.
main.py (생성됨):
- 그냥 테스트용 파일
2. 의존성 관리: 설치와 기록을 동시에
라이브러리 추가 (uv add)
uv add ~~ 해주면 uv.lock 파일이 탄생함. 이걸로 환경 공유함.
# 기본 설치
uv add torch torchvision
# 버전 지정 설치
uv add "numpy<2.0"
# 개발용 설치
uv add --dev pytest black
패키지 다운로드 및 설치:
.venv(가상환경) 폴더가 없으면 만들고, 그 안에 라이브러리를 깜.
pyproject.toml 수정:
- dependencies 항목에
torch, torchvision한 줄이 추가됨. (사람이 읽는 용도)
uv.lock 생성 또는 갱신 (중요):
- 이때
uv.lock파일이 자동으로 생성됨. - 설치된
torch의 정확한 버전(2.1.0 등)과 해시값이 여기에 기록됨.
동기화 (uv sync)
팀원이 올린 코드 받아서 실행할 때 쓰임
# 1. 깃 클론
git clone ~~~/model-repo.git
cd model-repo
# 2. 동기화 (이거 한 방이면 끝)
uv sync
uv.lock파일을 읽어서, 내 컴퓨터의 가상환경 상태를 그 파일과 100% 일치시킴.- 패키지가 없으면 깔고, 버전이 다르면 맞추고, 쓸데없는 게 깔려있으면 지워줌.
- 협업의 핵심: “너랑 나랑 환경이 달라서 에러 나는데?” 소리가 쏙 들어가버림.
3. 파이썬 버전 관리: 시스템 파이썬 건드리지 마라
서버에 깔린 /usr/bin/python3 건드리면 서버 관리자가 몽둥이 들고 쫓아옴ㄷㄷ.
버전 고정하기 (pin)
질문 답변: 언제 쓰노?
uv init을 하고 나면.python-version파일이 생기는데, 여기엔 기본적으로 내 컴퓨터의 현재 파이썬 버전이 들어감.- 근데 만약 “난 3.11 아니면 집에감 ㅅㄱ” 라고 버전을 강제하고 싶을 때 이 명령어를 씀.
# 실행 명령어: "이 프로젝트는 무조건 파이썬 3.11을 쓴다"
uv python pin 3.11
쓰면 뭐가 바뀌노?
.python-version 파일 내용 변경:
- 원래 3.12.1이 적혀있었다면, 명령어를 치는 순간 파일 내용이 3.11 (또는 구체적인 버전 cpython-3.11.9-linux-x86_64-gnu)로 바뀜.
- 이제 uv는 이 프로젝트에서 무조건 3.11 버전을 찾아 쓰고 없으면 다운로드 해줌.
uv.lock이나 pyproject.toml은?
pin명령어 자체는 주로.python-version파일만 건듦
실행하기 (run)
# 앞에 'uv run' 붙여서 실행하기.
uv run python train.py
# 가상환경 켜놓기, VSCode에선 이거 많이 쓰는듯
source .venv/bin/activate
uv run: 현재 프로젝트 폴더의.python-version을 확인하고, 그 버전에 맞는 가상환경을 찾아서 명령어를 실행해 줌.- 파이썬 3.11이 안 깔려 있다?
uv가 알아서 다운로드해서 가상환경 만들고 실행함. (개편함)
4. Docker 배포: 빌드 속도 10배 빠르게
# 1. 빌더 이미지 (여기서 설치 다 함)
FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim AS builder
WORKDIR /app
# [핵심 1] 의존성 명세서만 먼저 복사
# 소스코드(train.py)는 맨날 바뀌지만, 라이브러리 목록은 잘 안 바뀜.
# 이걸 먼저 복사해서 설치해야, 코드 고칠 때마다 라이브러리 다시 까는 멍청한 짓을 안 함.
COPY pyproject.toml uv.lock ./
# [핵심 2] 라이브러리 설치
# --frozen: 락파일 절대 준수 (맘대로 업데이트 금지)
# --no-install-project: 내 코드는 아직 깔지 마라
RUN uv sync --frozen --no-install-project --no-dev
# [핵심 3] 이제 소스코드 복사
COPY . .
# 프로젝트 설치 (필요시)
RUN uv sync --frozen --no-dev
# ==========================================
# 2. 실행 이미지 (가벼운 놈으로)
FROM python:3.11-slim-bookworm
WORKDIR /app
# 빌더에서 만든 가상환경(.venv)만 쏙 빼옴
COPY --from=builder /app/.venv /app/.venv
# [핵심 4] PATH 설정
# 가상환경 bin 폴더를 우선순위로 등록.
# 이제 'python' 치면 가상환경 파이썬이 실행됨.
ENV PATH="/app/.venv/bin:$PATH"
# 실행
CMD ["python", "src/train.py"]
이거는 알아두면 써먹을 때 분명히 있을듯. 클러스터든 뭐든 결국 도커 이미지 베이스로 뭐 깔고, 고치고, 스파링하고 하니까 ㅇㅇ
5. 요약: 이것만 기억하자
- 시작할 때:
uv init- 결과:
pyproject.toml,.python-version생성됨
- 결과:
- 깔 때:
pip install(X) ->uv add(O)- 결과:
uv.lock생성됨
- 결과:
- 버전 맞출 때:
uv python pin 3.11- 결과:
.python-version수정됨
- 결과:
- 실행할 때:
python main.py(X) ->uv run python main.py(O)- 혹은
source .venv/bin/activate
- 혹은
- 커밋할 때:
uv.lock파일은 무조건 Git에 올린다. (이거 안 올리면 죽음)