uv 로 관리한 프로젝트를 건네받으면 pyproject.toml 과 uv.lock 이 함께 온다. 둘 중 무엇이 실제 설치 버전을 정하는지 헷갈리면 배포 환경이 개발 환경과 어긋난다.
| 파일 | 내용 |
|---|---|
pyproject.toml |
원하는 의존성 조건. >= 같은 범위로 쓰는 것이 보통이다 |
uv.lock |
그 조건을 풀어서 확정한 정확한 버전. 간접 의존성과 플랫폼별 wheel 정보까지 포함한다 |
# pyproject.toml
[project]
name = "prediction"
requires-python = ">=3.10"
dependencies = [
"torch>=2.9.0",
"pandas>=2.3.2",
]
# uv.lock (일부)
[[package]]
name = "torch"
version = "2.9.1"
[[package]]
name = "numpy"
version = "2.2.6"
pyproject.toml 에는 numpy 가 없는데 uv.lock 에는 있다. 간접 의존성까지 고정되기 때문이다.
여기가 핵심이다. 잠금 파일이 있다고 해서 모든 설치가 그것을 따르지는 않는다.
| 명령 | 기준 | 결과 |
|---|---|---|
uv sync |
uv.lock |
완전히 재현된다 |
uv run <cmd> |
uv.lock |
필요하면 동기화한 뒤 실행한다 |
pip install . |
pyproject.toml |
잠금 파일을 무시하고 조건 안에서 최신을 설치한다 |
pip install -r requirements.txt |
그 파일 | 잠금 파일과 무관하다 |
pip install . 로 설치하면 오늘은 torch 2.9.1 이 깔리고 한 달 뒤에는 2.10.0 이 깔린다. 조건을 만족하므로 오류는 아니지만, 재현성이 필요한 배포에서는 이것이 사고의 출발점이 된다.
uv tree
uv pip list
grep -n '^name\|^version' uv.lock | head -60
uv tree 는 의존성 계층을 보여 주므로 어떤 패키지가 무엇 때문에 들어왔는지 추적할 때 쓴다.
uv 가 없는 환경에 설치해야 하거나, 컨테이너 이미지 빌드처럼 pip 만 있는 단계에 넘겨야 할 때가 있다. 잠금 파일을 손으로 옮겨 적지 말고 uv export 로 뽑는다.
uv export --format requirements-txt -o requirements.txt
옵션은 버전마다 늘어나므로 uv export --help 로 확인한다. 해시 포함 여부와 개발 의존성 포함 여부를 정하는 옵션이 있다. 해시가 들어간 파일은 pip 가 모든 패키지에 해시를 요구하게 되므로, 사내 미러를 쓰는 환경에서는 해시를 빼는 편이 설치가 수월하다. (확인 필요 — 정확한 플래그 이름은 설치된 uv 버전의 도움말로 확인한다.)
uv 를 쓸 수 없다면 실행 중인 환경에서 뽑는 방법도 있다.
pip freeze > requirements.txt
이 방법은 그 환경에 설치된 모든 것을 담으므로 프로젝트와 무관한 패키지까지 섞인다. 임시 수단으로만 쓴다.
uv.lock 은 잠글 때의 파이썬 버전과 플랫폼을 전제로 계산된 결과다. 대상 환경의 파이썬이 다르면 그대로 설치되지 않는 패키지가 나온다. 예를 들어 3.9 환경에 3.10 기준으로 잠근 파일을 밀어 넣으면 requires-python 에 걸려 거부된다.
이때는 두 갈래다.
버전 재현이 필요하면 대상 환경의 파이썬 버전을 프로젝트에 맞춘다. 관리형 플랫폼이라 파이썬 버전을 바꿀 수 없다면 프로젝트 쪽을 낮춰 다시 잠근다.
uv lock --python 3.10
"버전은 달라도 되고 라이브러리만 다 깔리면 된다" 면 잠금 파일을 버리고 pyproject.toml 의 조건만 쓴다.
pip install .
또는 조건만 뽑아 requirements.txt 로 만든 뒤 설치한다. 이 경우 재현성은 포기하는 것이며, 그 결정을 문서에 남겨 두는 편이 낫다.
uv.lock 은 저장소에 커밋한다. 이것이 없으면 재현이 불가능하다.uv.lock 을 손으로 고치지 않는다. uv add · uv lock 으로 다시 만든다.uv lock --check 로 pyproject.toml 과 어긋나 있는지 확인할 수 있다.