uv를 사용한 Python 패키지 관리 가이드
uv란?
uuv는 Astral에서 개발한 초고속 Python 패키지 관리자 및 실행기입니다. Rust로 작성되어 매우 빠르며, 패키지 설치, 의존성 관리, 가상 환경 생성, Python 버전 관리, 실행 등 Python 개발에 필요한 다양한 기능을 통합적으로 제공합니다. 기존의 pip, pip-tools, pipx, poetry, pyenv, virtualenv, twine 등을 대체할 수 있는 올인원 도구입니다.
공식 문서: uv Guides
1. uv 설치
macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# 또는
brew install uv
# 또는
pip install uv
Shell
복사
Windows (CMD, 터미널에서 실행할 때)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 또는
pip install uv
PowerShell
복사
•
위 명령어는 PowerShell을 외부에서 호출할 때 사용합니다.
•
ExecutionPolicy ByPass는 일시적으로 실행 제한을 우회합니다.
•
이미 PowerShell 내부에 있는 경우에는 아래처럼 더 간단하게 실행할 수도 있습니다:
irm https://astral.sh/uv/install.ps1 | iex
PowerShell
복사
설치 후 환경 변수 설정
•
설치 후 아래와 같은 명령어가 나온 경우 각자 터미널 환경에 맞게 명령어 복사 후 실행
설치 확인:
uv --version
Shell
복사
자세한 내용은 아래 설치 가이드 공식 문서를 참조하세요.
2. Python 설치 및 관리
uv는 Python이 시스템에 설치되어 있지 않아도 자동으로 필요한 버전을 설치합니다.
최신 Python 설치
uv python install
Shell
복사
특정 버전 설치
uv python install 3.12
Shell
복사
여러 버전 동시 설치
uv python install 3.10 3.11 3.12
Shell
복사
설치된 Python 버전 확인
uv python list
Shell
복사
uv는 Astral의 python-build-standalone 프로젝트를 통해 Python을 설치합니다. 설치된 Python은 시스템 전역에 영향을 주지 않습니다.
3. 프로젝트 초기화
새 프로젝트 생성
uv init my-project
cd my-project
Shell
복사
또는 현재 디렉토리를 프로젝트로 초기화하려면:
uv init
Shell
복사
중요: 위 명령어는 현재 디렉토리에 파일을 생성하므로, 명령어를 실행하는 위치(cmd 경로)가 매우 중요합니다. 원하지 않는 위치에서 실행하면 다른 프로젝트나 시스템 디렉토리에 파일이 생성될 수 있으니 주의하세요. 특정 Python 버전으로 초기화하기
특정 Python 버전을 사용하고 싶다면 --python 옵션을 사용하세요:
uv init my-project --python 3.11
cd my-project
Shell
복사
이렇게 하면 .python-version 파일에 해당 버전이 자동으로 지정됩니다.
또는 초기화 후 수동으로 버전을 설정할 수도 있습니다.
echo "3.11" > .python-version
Shell
복사
반드시 .python-version 파일이 있는 프로젝트 디렉토리에서 위 명령어를 실행해야 합니다.예: cd my-project로 이동한 후에 echo "3.11" > .python-version을 실행하세요.
.python-version 파일은 프로젝트에 사용될 Python 버전을 지정하며, uv나 pyenv 같은 도구들이 이 정보를 활용해 적절한 Python 환경을 자동으로 구성합니다.
지정한 Python 버전이 시스템에 없다면 uv가 자동으로 다운로드 및 설치해줍니다.생성되는 기본 파일
•
.python-version – 프로젝트의 Python 버전 지정
•
README.md – 프로젝트 설명 템플릿
•
main.py – 간단한 "Hello world" 프로그램 포함
•
pyproject.toml – 패키지 및 의존성 정의 파일
4. 가상 환경 생성 및 활성화
uv는 프로젝트 루트에 .venv 디렉토리를 생성하여 가상 환경을 관리합니다.
uv venv
Shell
복사
예를 들어, Python 3.10로 가상환경을 만들고 싶다면:
uv venv --python 3.10
Shell
복사
•
.venv/ 디렉토리에 Python 3.10 기반 가상환경 생성
대부분의 uv 명령어(uv pip, uv run 등)는 자동으로 가상 환경을 생성하고 활성화합니다.
별도로 source .venv/bin/activate 같은 명령은 필요 없습니다.
5. 패키지 설치 및 관리
패키지 설치
uv pip install 패키지명
Shell
복사
•
여러 패키지 동시 설치 예시 : uv pip install pandas matplotlib seaborn scikit-learn
설치된 패키지 목록 확인
uv pip freeze
Shell
복사
requirements.txt 파일 생성
uv pip freeze > requirements.txt
Shell
복사
requirements.txt 기반 설치
uv pip install -r requirements.txt
Shell
복사
uv는 pip과 완전히 호환되는 CLI를 제공하며 훨씬 빠르게 작동합니다.
pyproject.toml 기반 설치도 지원합니다.
6. 코드 실행
기본 실행
uv run python main.py
Shell
복사
특정 Python 버전으로 실행
uv run --python 3.10 main.py
Shell
복사
uv run 명령어 역시 자동으로 가상 환경을 생성 및 활성화합니다.
필요한 패키지와 함께 즉시 실행
#ex) requests 패키지 설치해서 example.py 코드 실행
uv run --with requests example.py
Shell
복사
Jupyter Notebook (.ipynb)에서 실행할 경우
.ipynb 파일을 VS Code에서 사용할 때는, .venv 가상환경을 커널(Kernel) 로 선택해야 해당 환경에 설치된 패키지들을 사용할 수 있습니다.
1.
.ipynb 파일을 엽니다.
2.
우측 상단의 Select Kernel 또는 Python 커널 선택 버튼 클릭
3.
목록에서 .venv 환경이 포함된 항목 선택
예: Python 3.10.13 ('.venv': venv)
.venv가 보이지 않는 경우, VS Code를 재시작 해보세요.
7. 가상 환경 제거
가상 환경을 제거하려면 .venv 폴더를 삭제합니다.
명령어 삭제 방법
rm -rf .venv
Shell
복사
또는 Windows에서는:
Remove-Item -Recurse -Force .venv
PowerShell
복사