파이쎤 uv 설치 방법

1.UV 설치 방법

Windows에서 UV를 설치하는 가장 권장되는 방법은 PowerShell을 이용한 스탠드얼론 설치입니다.

1.1. 권장 설치 방법 (PowerShell 스탠드얼론)

이 방법은 UV를 시스템 PATH에 독립적으로 설치하며, UV 자체 업데이트 기능도 포함되어 가장 편리합니다.

1. PowerShell 관리자 권한으로 실행:

   • Windows 시작 메뉴에서 "PowerShell"을 검색합니다.
   • "Windows PowerShell" 또는 "PowerShell"을 마우스 오른쪽 버튼으로 클릭하고 "관리자 권한으로 실행"을 선택합니다.
   • 사용자 계정 컨트롤(UAC) 메시지가 나타나면 "예"를 클릭합니다.

2. UV 설치 명령어 실행:

   • PowerShell 창에 다음 명령어를 입력하고 Enter를 누릅니다:
     powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   • 이 명령어는 Astral 공식 웹사이트에서 UV 설치 스크립트를 다운로드하여 실행합니다.

3. 설치 확인:

   • 설치가 완료되면, 현재 PowerShell 창을 닫고 새로 연 다음, 다음 명령어를 입력하여 UV가 제대로 설치되었는지 확인합니다:
     uv --version
   • UV 버전 정보가 출력되면 성공적으로 설치된 것입니다. (예: uv 0.1.X)

1.2. 다른 설치 방법 (참고)

• pipx를 이용한 설치 (Python 환경에 설치): pipx는 Python 애플리케이션을 격리된 환경에 설치하는 도구입니다. uv를 Python 애플리케이션으로 관리하고 싶을 때 사용합니다.
  pip install pipx # pipx가 없다면 먼저 설치

  pipx ensurepath    # pipx 경로를 PATH에 추가 (최초 1회)
  pipx install uv
  

  이 방법은 uv가 특정 Python 환경에 종속된다는 단점이 있습니다.

02. UV 주요 사용방

UV는 pip, venv, pip-tools의 기능을 통합하여 제공합니다.

2.1. 가상 환경 생성 및 활성화

uv 사용:

# 1. 프로젝트 디렉토리로 이동

cd my_project

# 2. 가상 환경 생성 (기본 이름: .venv)
uv venv

# 3. 가상 환경 활성화
# Windows (PowerShell):
.venv\Scripts\Activate.ps1

# Windows (Command Prompt):
.venv\Scripts\activate.bat

# Linux / macOS (Bash/Zsh):
source .venv/bin/activate

pip / venv 기존 사용:

# 1. 프로젝트 디렉토리로 이동

cd my_project

# 2. 가상 환경 생성 (기본 이름: .venv)
python -m venv .venv

# 3. 가상 환경 활성화 (UV와 동일)
# Windows (PowerShell):
.venv\Scripts\Activate.ps1

# Windows (Command Prompt):
.venv\Scripts\activate.bat

# Linux / macOS (Bash/Zsh):
source .venv/bin/activate

비교:

• uv는 uv venv 단일 명령어로 가상 환경을 생성합니다.
• 기존에는 python -m venv를 사용했습니다.
• 가상 환경 활성화 방법은 동일합니다.

2.2. 패키지 설치

uv 사용 (권장):

활성화된 가상 환경 내에서:

• uv pip install <패키지_이름>: 단일 패키지 설치
  uv pip install requests

  uv pip install flask==2.3.0 # 특정 버전 설치
  

• uv pip install -r requirements.txt: requirements.txt 파일의 패키지 설치
  uv pip install -r requirements.txt

비활성화된 상태에서 (특정 가상 환경에 설치):

• uv pip install -p ./.venv requests: . 대신 --python 또는 -p 옵션을 사용하여 특정 Python 실행 파일을 지정할 수도 있습니다.
  # .venv 가상환경에 requests 설치 (가상환경 활성화 안해도 됨)

  uv pip install -p ./.venv/Scripts/python.exe requests
  

pip 기존 사용:

활성화된 가상 환경 내에서:

• pip install <패키지_이름>: 단일 패키지 설치
  pip install requests

  pip install flask==2.3.0
  

• pip install -r requirements.txt: requirements.txt 파일의 패키지 설치
  pip install -r requirements.txt

비교:

• 핵심 차이: uv로 가상 환경을 생성했을 때 (특히 --seed 옵션 없이), 가상 환경 내부에 pip 실행 파일이 없을 수 있습니다. 이 경우, uv pip install을 사용해야 합니다.
  • uv pip install은 uv 자체가 패키지 설치를 담당하므로, 가상 환경 내부에 pip가 없어도 문제없이 작동합니다.
  • 만약 uv venv로 생성된 가상 환경에서 pip install을 직접 호출하면, 의도치 않게 시스템 전역의 pip가 호출되어 패키지가 전역에 설치되거나 오류가 발생할 수 있습니다.
• uv pip install은 pip install보다 훨씬 빠릅니다. (특히 의존성이 복잡하거나 많은 패키지를 설치할 때)
• uv는 패키지 캐싱을 효율적으로 관리하여 재설치 시 속도를 향상시킵니다.

2.3. 패키지 제거

uv 사용:

uv pip uninstall <패키지_이름>

uv pip uninstall requests flask

pip 기존 사용:

pip uninstall <패키지_이름>

pip uninstall requests flask

비교: 기능적으로 동일하지만 uv가 더 빠를 수 있습니다.

2.4. 설치된 패키지 목록 보기

uv 사용:

uv pip list

uv pip freeze > requirements.txt # 설치된 패키지를 requirements.txt로 저장

pip 기존 사용:

pip list

pip freeze > requirements.txt

비교: 기능적으로 동일하지만 uv가 더 빠를 수 있습니다.

2.5. 의존성 동기화 및 해결 (pip-tools 대체)

UV는 pip-tools의 pip-compile 및 pip-sync 기능을 통합하여 제공합니다.

uv 사용:

1. requirements.in 파일 생성:

   # requirements.in
   requests
   flask
   

2. 의존성 잠금 (requirements.txt 생성):

   uv pip compile requirements.in -o requirements.txt
   • 이 명령은 requirements.in에 명시된 상위 의존성과 그들의 모든 하위 의존성을 정확한 버전으로 requirements.txt 파일에 기록합니다.

3. 환경 동기화:

   uv pip sync requirements.txt
   • 이 명령은 requirements.txt에 명시된 패키지만 정확히 설치하고, requirements.txt에 없는 패키지는 제거합니다.

pip-tools 기존 사용:

1. **requirements.in 파일 생성 (동일)
2. 의존성 잠금 (requirements.txt 생성):
   pip-compile requirements.in -o requirements.txt
3. 환경 동기화:
   pip-sync requirements.txt

비교:

• uv는 pip-tools의 기능을 내장하여 별도의 설치 없이 사용할 수 있습니다.
• uv pip compile 및 uv pip sync는 pip-compile 및 pip-sync보다 훨씬 빠르고 효율적입니다.
• 의존성 해결 알고리즘도 개선되어 더 안정적인 의존성 그래프를 생성할 수 있습니다.

2.6. Python 버전 관리 (실험적 기능)

UV는 pyenv나 conda처럼 Python 버전을 설치하고 관리하는 기능도 실험적으로 제공합니다.

uv python install 3.12 # Python 3.12 설치

uv python list          # 설치된 Python 버전 목록
uv python find 3.10     # 특정 Python 버전의 경로 찾기

주의: 이 기능은 아직 uv의 초기 단계에 있으며, 모든 환경에서 완벽하게 작동하지 않을 수 있습니다.

03. UV와 PIP 비교

기능	Pip	UV (Ultraviolet)	비고
속도	느림 (특히 복잡한 의존성 해결 시)	매우 빠름 (Rust 기반, 병렬 처리)	UV의 가장 큰 장점.
설치 방식	pip install, python -m venv	uv (스탠드얼론 또는 pipx)	uv는 단일 바이너리로 통합된 기능을 제공.
가상 환경 관리	python -m venv (별도 모듈)	uv venv (내장)	uv는 가상 환경 생성 및 관리를 통합.
패키지 설치 명령어	pip install	uv pip install	uv 가상 환경에서는 uv pip install이 권장/필수.
의존성 해결	기본적인 알고리즘	고급 알고리즘 (최신 resolver)	의존성 충돌 발생 가능성이 낮고, 더 일관된 결과 제공.
의존성 고정/동기화	pip-tools (별도 설치 필요)	uv pip compile, uv pip sync (내장)	pip-tools의 핵심 기능을 UV에 내장하여 워크플로우 간소화.
캐싱	기본적인 캐싱 (잘 관리되지 않으면 문제 발생)	효율적인 캐싱 (재설치 시 속도 개선)	패키지 다운로드 및 빌드 시간을 절약.
Python 버전 관리	없음	uv python install (실험적)	pyenv 또는 conda의 기능 일부를 통합 시도.
사용 편의성	여러 도구를 조합해야 함 (pip, venv, pip-tools)	통합된 워크플로우 (단일 도구로 대부분 처리)	학습 곡선이 낮고, 일관된 명령어로 편리하게 사용 가능.
Rust 기반	Python으로 작성됨	Rust로 작성됨	속도와 안전성 측면에서 유리.
커뮤니티/생태계	매우 크고 성숙함	빠르게 성장 중	아직 pip만큼 크지는 않지만, 빠르게 채택되고 있음.

---

결론

uv는 Python 패키지 관리를 위한 차세대 도구로, 기존 pip와 venv의 단점(느린 속도, 복잡한 워크플로우)을 보완하고 더 나은 사용자 경험을 제공합니다. 특히 대규모 프로젝트나 CI/CD 환경에서 빠른 속도는 엄청난 이점으로 작용합니다.

uv로 새로운 프로젝트를 시작하거나, 기존 프로젝트를 uv로 전환하여 사용해 보는 것을 강력히 추천합니다. 처음에는 uv pip install과 같이 명령어가 약간 다르게 느껴질 수 있지만, 그 효율성과 편리함에 곧 익숙해지실 겁니다.

기타 참고

uv로 가상 환경을 생성할 때 파이썬 버전을 지정하지 않으면, uv는 다음과 같은 방식으로 파이썬 인터프리터를 찾아서 사용합니다:

1. uv venv 시 파이썬 버전 지정하지 않을 경우

uv는 기본적으로 시스템에서 찾을 수 있는 가장 최신 버전의 Python을 사용하여 가상 환경을 생성합니다.

• 탐색 순서 (일반적인 경우):
  1. 현재 작업 디렉토리 또는 부모 디렉토리에 있는 .python-version 파일에서 지정된 버전이 있는지 확인합니다.
  2. 시스템 PATH에 있는 Python 실행 파일 중 uv가 인식하는 가장 최신 버전을 사용합니다.
  3. 만약 시스템에 적합한 Python 버전이 없다면, uv가 자동으로 최신 Python 버전을 다운로드하여 관리되는 Python 버전으로 설치하고 이를 사용하여 가상 환경을 생성할 수 있습니다. (uv의 python-downloads 설정에 따라 달라짐)

간단히 말해, 명시적으로 지정하지 않으면 uv는 "가장 최신 버전의 파이썬"을 선호한다고 생각하시면 됩니다.

2. 특정 파이썬 버전으로 가상 환경 생성하는 방법

특정 파이썬 버전으로 가상 환경을 생성하려면 uv venv 명령어에 --python (또는 -p) 옵션을 사용하면 됩니다.

기본 형식:

uv venv --python <원하는_파이썬_버전>

예시:

1. 특정 주 버전(Major version) 지정:

   uv venv --python 3.11

   # 시스템에 Python 3.11이 있다면 이를 사용하고, 없다면 3.11의 최신 마이너 버전을 자동으로 다운로드하여 설치합니다.
   

2. 특정 마이너 버전(Minor version)까지 정확히 지정:

   uv venv --python 3.11.8

   # 정확히 Python 3.11.8을 찾거나 다운로드하여 사용합니다.
   

3. 버전 범위 지정 (고급):

   uv venv --python ">=3.10,<3.12"

   # Python 3.10 이상 3.12 미만의 버전 중 가장 적합한 버전을 찾아 사용합니다.
   

중요 사항:

• 자동 다운로드: 만약 --python으로 지정한 버전이 시스템에 설치되어 있지 않다면, uv는 해당 버전을 자동으로 다운로드하여 설치하고 가상 환경을 생성합니다. 이는 pyenv나 conda와 유사한 uv의 Python 버전 관리 기능 덕분입니다.
• .python-version 파일 활용: 프로젝트 루트에 .python-version 파일을 생성하고 원하는 파이썬 버전을 기록해두면, 해당 디렉토리에서 uv venv 명령어를 --python 옵션 없이 실행해도 uv가 해당 파일에 명시된 버전을 사용합니다. 예:

  # .python-version 파일 내용
  3.10
  

  이후 uv venv 실행 시 Python 3.10으로 가상 환경이 생성됩니다. 여러 버전을 나열하면 uv는 목록에서 첫 번째로 찾은 버전을 사용하려고 시도합니다.

예시 시나리오:

프로젝트 A는 Python 3.9가 필요하고, 프로젝트 B는 Python 3.11이 필요하다고 가정해봅시다.

프로젝트 A (Python 3.9):

mkdir project_a

cd project_a
uv venv --python 3.9
# 이제 project_a/.venv 는 Python 3.9로 생성됩니다.
.venv\Scripts\Activate.ps1
uv pip install requests

프로젝트 B (Python 3.11):

mkdir project_b

cd project_b
uv venv --python 3.11
# 이제 project_b/.venv 는 Python 3.11로 생성됩니다.
.venv\Scripts\Activate.ps1
uv pip install flask

이처럼 uv의 --python 옵션을 사용하면 프로젝트별로 필요한 파이썬 버전을 유연하게 지정하고 관리할 수 있습니다.

uv나 python -m venv와 같은 도구를 사용하여 가상 환경을 생성할 때, 두 가지 시나리오를 구분해서 이해하는 것이 중요합니다.

1. 가상 환경 내부에 Python 인터프리터가 "링크"되거나 "복사"되는 경우 (기존 venv의 기본 동작)

대부분의 경우 (특히 python -m venv를 사용하거나 uv venv가 시스템에 이미 존재하는 Python 버전을 사용할 때), 가상 환경은 실제로 시스템에 설치된 특정 Python 인터프리터를 "참조"하거나 필요한 파일만 "복사"하여 생성됩니다.

• 설치된 Python: 시스템 어딘가에 (예: C:\Python39 또는 C:\Users\YourUser\AppData\Local\Programs\Python\Python310) 실제 Python 인터프리터가 설치되어 있습니다.
• 가상 환경 생성: uv venv 명령을 실행하면, 프로젝트 폴더 안에 .venv (또는 지정한 이름) 폴더가 생기고, 이 안에 자체적인 Scripts (Windows) 또는 bin (Linux/macOS) 폴더가 만들어집니다. 이 폴더 안에는 시스템의 Python 인터프리터를 가리키는 심볼릭 링크(바로가기)가 생성되거나, 필요한 핵심 실행 파일이 복사됩니다.
• 패키지 설치: 가상 환경을 활성화하고 패키지를 설치하면, 이 패키지들은 모두 가상 환경 폴더 내의 Lib\site-packages (Windows) 또는 lib/pythonX.Y/site-packages (Linux/macOS)에 저장됩니다.

이 시나리오에서 가상 환경 삭제 시:

• 가상 환경 폴더 (.venv)를 삭제하면, 그 안에 설치된 모든 패키지와 가상 환경 관련 파일(스크립트, 링크 등)은 함께 삭제됩니다.
• 하지만 가상 환경이 참조했던 "시스템에 원래 설치되어 있던" 실제 Python 인터프리터는 그대로 남아 있습니다. 가상 환경은 그 Python을 활용한 것뿐이지, 독립적인 새 Python을 통째로 설치한 것이 아닙니다.

2. uv가 Python 버전을 "관리되는 Python"으로 다운로드하고 설치하는 경우 (UV의 특정 기능)

uv는 --python 옵션으로 특정 Python 버전을 지정했을 때, 만약 해당 버전이 시스템에 없다면 자신이 직접 해당 Python 버전을 다운로드하여 관리합니다.

• uv가 다운로드한 Python: 이 Python 버전은 일반적으로 uv의 캐시 디렉토리(예: C:\Users\YourUser\AppData\Local\uv\python-downloads 또는 ~/.cache/uv/python-downloads) 내에 설치됩니다. 이것은 시스템 전체에 깔리는 Python과는 별개로 uv가 사용하는 Python입니다.
• 가상 환경 생성: uv는 이 자신이 관리하는 Python을 사용하여 가상 환경을 생성합니다.

이 시나리오에서 가상 환경 삭제 시:

• 가상 환경 폴더 (.venv)를 삭제하면, 그 안에 설치된 모든 패키지와 가상 환경 관련 파일은 함께 삭제됩니다.
• uv가 다운로드하여 캐시 디렉토리에 설치했던 "관리되는 Python"은 자동으로 삭제되지 않습니다. uv는 이 Python 버전을 다른 가상 환경에서도 재사용할 수 있도록 유지합니다.
• uv가 관리하는 Python 버전을 명시적으로 삭제하려면 uv python uninstall <버전> 명령을 사용해야 합니다.

요약

특징	가상 환경 삭제 시	시스템에 설치된 Python	uv가 다운로드한 Python
패키지	삭제됨 (.venv 폴더와 함께)	N/A	N/A
가상 환경 파일	삭제됨 (.venv 폴더와 함께)	N/A	N/A
원래의 Python 인터프리터	삭제되지 않음 (.venv가 참조하던 시스템 Python)	그대로 유지	그대로 유지
uv가 다운로드한 Python	삭제되지 않음 (uv 캐시에 유지)	N/A	그대로 유지

따라서 "가상에 파이썬이 설치된다"는 표현은 가상 환경이 독립적인 파이썬 실행 환경을 제공한다는 의미에서 맞지만, 그 독립적인 환경을 구성하는 방식이 시스템 Python을 참조하는 방식일 수도 있고, uv가 별도로 관리하는 Python을 사용하는 방식일 수도 있다는 점을 이해하시면 됩니다. 어느 쪽이든, 가상 환경 폴더 자체를 삭제하면 그 안에 설치된 패키지들은 모두 사라집니다.