Dependency Management in uv : A Developer’s Guide

uv를 PMS Backend에 적용해보면서 과정을 기록하고 궁금한 점 해소를 문서화합니다.

uv install

https://docs.astral.sh/uv/getting-started/installation/

brew install uv # macOS/Linux
https://docs.astral.sh/uv/getting-started/installation/

# window
powershell -c "irm https://astral.sh/uv/install.ps1 | more"

• app에 python 3.12로 uv init 구조는 현재 PMS처럼 프로젝트 root에 app이라는 폴더를 생성하여 그 안에 fastapi를 구성했다는 전제
  

uv init --app --python 3.12  # 프로젝트 초기화 (Python 3.12)

uv add fastapi --extra standard  # FastAPI 설치

source .venv/bin/activate  # 가상 환경 활성화

uv pip install -r requirements-dev.txt  # 기존 의존성 설치

uv run fastapi dev  # FastAPI 서버 실행

Pytest Command

uv run pytest -v -s -x --disable-warnings tests/test_ldh.py

---

✅ uv.lock 파일을 .gitignore에 추가해야 할까?

위에서 uv를 사용할 때 requirements-dev.txt로 우선적으로 마이그레이션을 진행하였다.

이러면 uv.lock이라는 파일이 생기고 이 안에 dependency에 관한 내용들이 전부 들어있다.

정답: 프로젝트의 성격에 따라 다름

---

📌 uv.lock 파일이란?

• uv.lock은 설치된 패키지의 정확한 버전과 의존성을 고정하는 파일이다.
• requirements.txt와 비슷하지만, 더 정확한 버전 및 의존성 충돌 해결 정보가 포함된다.
• 프로젝트를 완전히 동일한 환경에서 실행하려면 uv.lock을 공유하는 것이 좋다. uv.lock에는 버전 값이 고정되어있기 때문
  

---

📌 uv.lock을 .gitignore에 추가해야 할까?

uv.lock을 Git에 포함해야 하는 경우 ( 일반적인 웹 서비스, 백엔드 프로젝트)

🚀 권장: 팀원들과 동일한 패키지 버전을 유지하려면 uv.lock을 Git에 포함하는 것이 좋음

• 패키지 버전이 변경되지 않도록 고정된 상태로 유지됨
• 배포 환경과 개발 환경의 패키지 버전이 일관되게 유지됨
• 예제: FastAPI, Django, Flask, Spring Boot 등의 백엔드 프로젝트

결론: ❌ .gitignore에 추가하지 않음 → Git에 커밋해야 함

uv.lock과 pyproject.toml 차이점은?

현재 기존의 PMS Backend를 uv 환경에서 실행하기 위해 uv 명령어를 통해 requirements-dev.txt의 의존성을 설치하였다.

이때 uv.lock에 설치한 의존성 정보가 전부 저장되었으나 pyproject.toml에는 저장되지 않았다.

📌 pyproject.toml vs uv.lock

❓ uv.lock만 사용하면 되는데, pyproject.toml이 필요한 이유?

파일	역할	예제
pyproject.toml	필요한 패키지 정의 (버전 범위 허용)	fastapi = "^0.115.8"
uv.lock	설치된 패키지 버전 및 의존성 정확히 기록	fastapi-0.115.8 (해시 포함)

📌 쉽게 말하면:

• pyproject.toml → "나는 fastapi가 필요해. 최신 0.115.x까지 가능"
• uv.lock → "현재 fastapi==0.115.8을 쓰고 있음 (의존성 포함, 고정됨)"

✅ pyproject.toml만 있으면? → 패키지 설치할 때마다 최신 버전이 깔릴 수 있어 팀마다 버전이 다를 수 있음

✅ uv.lock만 있으면? → 사람이 직접 수정하기 어렵고, 새로운 패키지 추가가 불편함

✅ 둘 다 있으면? → 패키지 관리가 깔끔하고, 팀 전체가 동일한 환경을 유지할 수 있음

---

추천 방법 (실제 프로젝트에서)

1️⃣ 새로운 패키지 추가할 때:

uv add numpy

• pyproject.toml + uv.lock 자동 업데이트

2️⃣ 팀원이 패키지 설치할 때:

uv pip install

uv pip install 실행 시 어떻게 동작하는가?

• uv pip install을 실행하면 uv.lock을 참고하여 패키지를 설치한다. 즉, 항상 uv.lock에 기록된 정확한 버전이 설치된다.
  

📌 정확한 동작 방식:

1. uv.lock 파일이 존재하면 → uv.lock의 정보를 사용하여 고정된 패키지 버전을 설치
2. uv.lock 파일이 없으면 → pyproject.toml을 기반으로 최신 호환 버전을 찾아 설치
3. uv.lock이 오래되었으면 → uv pip compile을 실행하여 pyproject.toml과 동기화

---

📌 uv 적용 과정에서 얻은 교훈

1. 의존성 관리 속도가 확실히 빠름
2. 패키지 충돌 방지가 쉬워짐 (uv.lock 덕분)
3. 기존 pip 방식에서 무리 없이 전환 가능
4. 처음부터 uv로 시작하면 requirements.txt가 필요 없음

---

📌 참고 문서

• uv 공식 문서
• FastAPI & uv 사용 가이드
• Python 패키지 관리 uv 정리
• Python FastAPI quickstart in uv

공식문서:

https://docs.astral.sh/uv/guides/install-python/
https://docs.astral.sh/uv/guides/integration/fastapi/