파이썬 환경¶
각 파이썬 설치에는 파이썬을 사용할 때 활성화되는 환경이 있다. 환경에 패키지를 설치하면 파이썬 스크립트에서 해당 모듈을 사용할 수 있다. 일반적으로 파이썬 설치 환경을 수정하지 않는 것이 좋은 관행으로 여겨진다. 특히 운영체제와 함께 제공되는 파이썬 설치의 경우, 이들 환경은 종종 패키지를 직접 관리하므로 더욱 중요하다. 가상 환경은 파이썬 설치 환경에서 패키지를 격리하는 가벼운 방법이다. pip와 달리, uv는 기본적으로 가상 환경을 사용해야 한다.
가상 환경 생성¶
uv는 가상 환경을 생성하는 기능을 지원한다. 예를 들어 .venv 위치에 가상 환경을 생성하려면 다음과 같이 명령한다:
$ uv venv
특정 이름이나 경로를 지정할 수도 있다. 예를 들어 my-name에 가상 환경을 생성하려면 다음과 같이 명령한다:
$ uv venv my-name
Python 버전을 지정할 수도 있다. 예를 들어 Python 3.11 버전으로 가상 환경을 생성하려면 다음과 같이 명령한다:
$ uv venv --python 3.11
이 경우 시스템에 해당 Python 버전이 설치되어 있어야 한다. 하지만 설치되어 있지 않으면 uv가 자동으로 Python을 다운로드한다. 자세한 내용은 Python 버전 문서를 참고한다.
가상 환경 사용하기¶
기본 가상 환경 이름을 사용하면, uv는 이후 호출 시 자동으로 가상 환경을 찾아 사용한다.
$ uv venv
$ # 새 가상 환경에 패키지 설치
$ uv pip install ruff
가상 환경을 "활성화"하면 해당 환경의 패키지를 사용할 수 있다:
=== "macOS와 Linux"
```console
$ source .venv/bin/activate
```
=== "Windows"
```console
$ .venv\Scripts\activate
```
Note
Unix에서 기본 활성화 스크립트는 sh, bash, zsh와 같은 POSIX 호환 쉘을 위한 것이다. 일반적인 대체 쉘을 위한 추가 활성화 스크립트도 있다.
=== "fish"
```console
$ source .venv/bin/activate.fish
```
=== "csh / tcsh"
```console
$ source .venv/bin/activate.csh
```
=== "Nushell"
```console
$ use .venv\Scripts\activate.nu
```
가상 환경 비활성화¶
가상 환경을 종료하려면 deactivate 명령어를 사용한다:
$ deactivate
임의의 Python 환경 사용하기¶
uv는 Python에 의존하지 않기 때문에, 자신이 설치된 환경 외의 가상 환경에도 설치할 수 있다. 예를 들어, VIRTUAL_ENV=/path/to/venv로 설정하면 uv는 /path/to/venv에 설치된다. 이때 uv가 어디에 설치되었는지는 중요하지 않다. 단, VIRTUAL_ENV가 PEP 405 표준을 준수하지 않는 가상 환경 디렉토리로 설정된 경우, 이 설정은 무시된다.
uv는 uv pip sync 또는 uv pip install에 --python 인자를 제공해 임의의 환경, 심지어 가상 환경이 아닌 환경에도 설치할 수 있다. 예를 들어, uv pip install --python /path/to/python은 /path/to/python 인터프리터와 연결된 환경에 설치한다.
편의를 위해 uv pip install --system은 시스템 Python 환경에 설치한다. --system은 uv pip install --python $(which python)과 거의 동일하지만, 가상 환경에 연결된 실행 파일은 건너뛴다. 일반적으로 의존성 관리를 위해 가상 환경을 사용할 것을 권장하지만, 지속적 통합(CI)이나 컨테이너화된 환경에서는 --system이 적합하다.
--system 플래그는 시스템 환경을 변경하기 위해 사용되기도 한다. 예를 들어, --python 인자로 특정 Python 버전(예: --python 3.12)을 요청하면, uv는 해당 요청을 충족하는 인터프리터를 찾는다. 만약 uv가 시스템 인터프리터(예: /usr/lib/python3.12)를 찾은 경우, 이 비가상 Python 환경을 수정하려면 --system 플래그가 필요하다. --system 플래그 없이는 uv는 가상 환경이 아닌 인터프리터를 무시한다. 반대로 --system 플래그가 제공되면, uv는 가상 환경에 있는 인터프리터를 무시한다.
플랫폼과 배포판에 걸쳐 시스템 Python에 설치하는 것은 유명하게 어려운 작업이다. uv는 일반적인 경우를 지원하지만, 모든 경우에 작동하지는 않는다. 예를 들어, Python 3.10 이전의 Debian에서는 시스템 Python에 설치하는 것이 지원되지 않는다. 이는 배포판이 distutils(하지만 sysconfig는 아님)를 패치했기 때문이다. 비표준 환경에서는 가상 환경 사용을 권장하며, uv도 이를 필수로 간주한다.
uv가 Python 환경에 설치된 경우(예: pip로 설치), 여전히 다른 환경을 수정하는 데 사용할 수 있다. 그러나 python -m uv로 호출하면 uv는 기본적으로 부모 인터프리터의 환경을 사용한다. Python을 통해 uv를 호출하면 시작 오버헤드가 추가되므로 일반적인 사용에는 권장하지 않는다.
uv 자체는 Python에 의존하지 않지만, (1) 환경에 의존성을 설치하고 (2) 소스 배포판을 빌드하기 위해 Python 환경을 찾아야 한다.
파이썬 환경 탐색¶
uv pip sync나 uv pip install과 같이 환경을 변경하는 커맨드를 실행할 때, uv는 다음 순서대로 가상 환경을 탐색한다:
VIRTUAL_ENV환경 변수를 기반으로 활성화된 가상 환경CONDA_PREFIX환경 변수를 기반으로 활성화된 Conda 환경- 현재 디렉토리나 가장 가까운 상위 디렉토리의
.venv에 위치한 가상 환경
만약 가상 환경을 찾지 못하면, uv는 현재 디렉토리에 가상 환경을 생성하도록 uv venv를 통해 사용자에게 프롬프트를 표시한다.
--system 플래그를 포함하면, uv는 가상 환경 탐색을 건너뛰고 설치된 파이썬 버전을 찾는다. 마찬가지로, uv pip compile과 같이 환경을 변경하지 않는 커맨드를 실행할 때는 가상 환경이 필수적이지 않다. 하지만 파이썬 인터프리터는 여전히 필요하다. 설치된 파이썬 버전을 탐색하는 방법에 대한 자세한 내용은 파이썬 버전 탐색 문서를 참고한다.