UV: 프로젝트 라이브러리 관리 uv 사용법

🚀 uv 사용법 간단 정리

1. 가상환경 해제

기존에 활성화된 .venv 가상환경이 있다면 deactivate 명령어로 비활성화합니다.

Bash

 

deactivate

---

2. uv 초기 설정

uv init 명령어를 실행하면 프로젝트 기본 파일들이 생성됩니다.

• .gitignore
• .python-version
• main.py
• pyproject.toml
• README.md

이후 **uv run python**을 실행하면 .venv 가상환경 폴더와 uv.lock 파일이 생성되며 가상환경이 구축됩니다.

---

3. 파이썬 버전 변경 버전 관리 🔧

.python-version 파일에 원하는 파이썬 버전을 수정합니다. (예: 3.11 -> 3.12)

# .python-version 파일 내용
3.12

수정 후 **uv run python**을 다시 실행하면 uv가 해당 버전을 감지하여 자동으로 설치하고 적용해 줍니다.

---

4. 라이브러리 관리 (pyproject.toml & uv.lock)

uv는 pyproject.toml 파일을 통해 프로젝트의 의존성을 관리합니다.

• 패키지 추가: uv add [패키지명]
  • 예: uv add numpy
  • 명령어 실행 시, numpy가 가상환경에 설치되고 pyproject.toml과 uv.lock 파일에 해당 의존성이 기록됩니다.
• 패키지 삭제: uv remove [패키지명]
  • 예: uv remove numpy
  • 마찬가지로 가상환경에서 삭제되고, 관련 파일에서도 내용이 업데이트됩니다.

pyproject.toml은 설치된 라이브러리 목록을 간결하게 보여주고, uv.lock은 모든 의존성에 대한 상세 정보를 담고 있습니다.

---

5. 협업 및 환경 동기화 🤝

.venv 폴더는 용량이 크기 때문에 보통 .gitignore에 추가하여 Git 저장소에 올리지 않습니다.

다른 팀원이 프로젝트를 클론한 후, 필요한 라이브러리를 일일이 설치할 필요 없이 uv sync 명령어 하나만 실행하면 pyproject.toml과 uv.lock 파일을 기반으로 모든 의존성이 자동으로 설치됩니다.

✨ 꿀팁: 사실 uv run 명령어를 실행하면 내부적으로 uv sync가 먼저 실행됩니다. 그래서 대부분의 경우 uv run만으로도 충분합니다!

---

6. uv add vs uv pip install

명령어	pyproject.toml 기록	설명
uv add [패키지명]	O (기록됨)	프로젝트의 공식 의존성으로 추가. 협업 시 공유됨.
uv pip install [패키지명]	X (기록 안됨)	가상환경(.venv)에 임시로 설치만 할 때 사용. 프로젝트 의존성 파일에는 반영되지 않음.

Sheets로 내보내기

결론: 프로젝트에 필요한 라이브러리는 꼭 **uv add**를 사용해서 관리하는 것이 좋습니다.