환경 변수¶
uv는 다음 환경 변수를 정의하고 준수한다:
UV_BREAK_SYSTEM_PACKAGES¶
이 옵션은 --break-system-packages 커맨드라인 인자와 동일하다. 값을 true로 설정하면, uv는 시스템에 설치된 패키지와 충돌하는 패키지의 설치를 허용한다.
경고: UV_BREAK_SYSTEM_PACKAGES=true는 지속적 통합(CI)이나 컨테이너 환경에서 사용하기 위한 목적이다. 시스템 Python을 수정하면 예상치 못한 동작이 발생할 수 있으므로 주의해서 사용해야 한다.
UV_BUILD_CONSTRAINT¶
--build-constraint 커맨드라인 인자와 동일한 기능을 한다. 설정하면, uv는 이 파일을 소스 배포 빌드에 대한 제약 조건으로 사용한다. 공백으로 구분된 파일 목록을 사용한다.
UV_CACHE_DIR¶
--cache-dir 커맨드라인 인자와 동일한 역할을 한다. 이 값을 설정하면, uv는 기본 캐시 디렉터리 대신 이 디렉터리를 사용한다.
UV_COMPILE_BYTECODE¶
--compile-bytecode 커맨드라인 인자와 동일한 기능을 한다. 이 옵션을 설정하면 uv는 설치 후에 Python 소스 파일을 바이트코드로 컴파일한다.
UV_CONCURRENT_BUILDS¶
uv가 동시에 빌드할 수 있는 소스 배포의 최대 개수를 설정한다.
UV_CONCURRENT_DOWNLOADS¶
이 설정은 uv가 동시에 처리할 수 있는 최대 다운로드 수를 지정한다.
UV_CONCURRENT_INSTALLS¶
패키지를 설치하고 압축을 해제할 때 사용할 스레드 수를 제어한다.
UV_CONFIG_FILE¶
--config-file 커맨드라인 인수와 동일하다. 설정 파일로 사용할 로컬 uv.toml 파일의 경로를 지정한다.
UV_CONSTRAINT¶
--constraint 커맨드라인 인자와 동일한 역할을 한다. 이 값을 설정하면 uv는 해당 파일을 제약 조건 파일로 사용한다. 여러 파일을 공백으로 구분하여 지정할 수 있다.
UV_CUSTOM_COMPILE_COMMAND¶
--custom-compile-command 커맨드라인 인자와 동일한 기능을 한다.
uv pip compile로 생성된 requirements.txt 파일의 출력 헤더에서 uv를 대체하기 위해 사용한다. uv pip compile이 래퍼 스크립트 내부에서 호출되는 경우, 출력 파일에 래퍼 스크립트의 이름을 포함시키기 위한 목적으로 활용한다.
UV_DEFAULT_INDEX¶
--default-index 커맨드라인 인자와 동일한 기능을 한다. 이 값을 설정하면 uv는 패키지를 검색할 때 이 URL을 기본 인덱스로 사용한다.
UV_ENV_FILE¶
uv run 명령을 실행할 때 환경 변수를 로드할 .env 파일을 지정한다.
UV_EXCLUDE_NEWER¶
이 옵션은 --exclude-newer 커맨드라인 인자와 동일한 기능을 한다. 설정하면 uv는 지정된 날짜 이후에 발행된 배포판을 제외한다.
UV_EXTRA_INDEX_URL¶
이 환경 변수는 --extra-index-url 커맨드라인 인자와 동일한 기능을 한다. 설정하면, uv는 패키지를 검색할 때 이 공백으로 구분된 URL 목록을 추가 인덱스로 사용한다. (더 이상 사용되지 않음: UV_INDEX를 대신 사용한다.)
UV_FIND_LINKS¶
--find-links 커맨드라인 인자와 동일한 기능을 한다. 이 값을 설정하면, uv는 추가 패키지 검색 위치로 사용할 쉼표로 구분된 목록을 활용한다.
UV_FORK_STRATEGY¶
--fork-strategy 인자와 동일한 기능을 한다. 유니버설 해결 과정에서 버전 선택을 제어한다.
UV_FROZEN¶
--frozen 커맨드라인 인수와 동일하다. 이 값이 설정되면, uv는 uv.lock 파일을 업데이트하지 않고 실행된다.
UV_GITHUB_TOKEN¶
--token 인자와 동일하며, 자체 업데이트를 위한 GitHub 토큰을 의미한다. 인증을 위해 사용한다.
UV_GIT_LFS¶
Git 저장소에서 패키지를 설치할 때 Git LFS에 저장된 파일을 가져오는 기능을 활성화한다.
UV_HTTP_TIMEOUT¶
HTTP 요청에 대한 타임아웃(초 단위)을 설정한다. 기본값은 30초이다.
UV_INDEX¶
--index 커맨드라인 인자와 동일한 기능을 한다. 설정하면, uv는 패키지를 검색할 때 이 공백으로 구분된 URL 목록을 추가 인덱스로 사용한다.
UV_INDEX_STRATEGY¶
--index-strategy 커맨드라인 인자와 동일한 기능을 한다.
예를 들어, 이 값을 unsafe-any-match로 설정하면 uv는 특정 패키지의 버전을 모든 인덱스 URL에서 검색한다. 패키지가 포함된 첫 번째 인덱스 URL로 검색을 제한하지 않는다.
UV_INDEX_URL¶
이 설정은 --index-url 커맨드라인 인자와 동일한 역할을 한다. 설정하면 uv는 패키지를 검색할 때 이 URL을 기본 인덱스로 사용한다.
(더 이상 사용되지 않음: UV_DEFAULT_INDEX를 대신 사용한다.)
UV_INDEX_{name}_PASSWORD¶
지정된 인덱스에 대한 HTTP 기본 인증 비밀번호를 제공한다.
name 파라미터는 인덱스의 이름을 나타낸다. 예를 들어, foo라는 이름의 인덱스가 있다면, 환경 변수 키는 UV_INDEX_FOO_PASSWORD가 된다.
UV_INDEX_{name}_USERNAME¶
특정 이름의 인덱스에 대한 HTTP 기본 인증 사용자 이름을 제공한다.
name 파라미터는 인덱스의 이름을 의미한다. 예를 들어, foo라는 이름의 인덱스가 있다면, 환경 변수 키는 UV_INDEX_FOO_USERNAME이 된다.
UV_INSECURE_HOST¶
--allow-insecure-host 인자와 동일한 기능을 한다.
UV_INSTALLER_GHE_BASE_URL¶
독자가 기본 GitHub Enterprise URL 대신 사용할 수 있는 URL이다. 이 URL은 독립형 설치 프로그램과 self update 기능을 통해 uv를 다운로드할 때 활용된다.
UV_INSTALLER_GITHUB_BASE_URL¶
독립형 설치 프로그램과 self update 기능을 통해 uv를 다운로드할 때 사용할 기본 GitHub URL 대신 사용할 URL이다.
UV_INSTALL_DIR¶
uv를 독립 실행형 설치 프로그램과 self update 기능을 통해 설치할 디렉터리. 기본값은 ~/.local/bin이다.
UV_KEYRING_PROVIDER¶
이 값은 --keyring-provider 커맨드라인 인자와 동일하다. 설정하면, uv는 이 값을 키링 프로바이더로 사용한다.
UV_LINK_MODE¶
--link-mode 커맨드라인 인자와 동일한 역할을 한다. 설정하면 uv가 이 값을 링크 모드로 사용한다.
UV_LOCKED¶
--locked 커맨드라인 인수와 동일한 기능을 한다. 이 옵션을 설정하면 uv는 uv.lock 파일이 변경되지 않았음을 확인한다.
UV_NATIVE_TLS¶
--native-tls 커맨드라인 인자와 동일한 기능을 한다. 이 값을 true로 설정하면, uv는 기본 제공되는 webpki-roots 크레이트 대신 시스템의 신뢰 저장소를 사용한다.
UV_NO_BINARY¶
이 옵션은 --no-binary 커맨드라인 인자와 동일하다. 설정하면 uv는 모든 패키지를 소스에서 설치한다. 하지만 리졸버는 가능한 경우 사전 빌드된 휠을 사용해 패키지 메타데이터를 추출한다.
UV_NO_BINARY_PACKAGE¶
--no-binary-package 커맨드라인 인수와 동일한 역할을 한다. 이 값을 설정하면 uv는 공백으로 구분된 패키지 목록에 대해 사전 빌드된 휠을 사용하지 않는다.
UV_NO_BUILD_ISOLATION¶
UV_NO_BUILD_ISOLATION은 --no-build-isolation 커맨드라인 인자와 동일하다. 이 값이 설정되면, uv는 소스 배포물을 빌드할 때 격리 과정을 건너뛴다.
UV_NO_CACHE¶
--no-cache 커맨드라인 인수와 동일하다. 이 값을 설정하면 uv는 모든 작업에서 캐시를 사용하지 않는다.
UV_NO_CONFIG¶
이 옵션은 --no-config 커맨드라인 인자와 동일하다. 이 값을 설정하면 uv는 현재 디렉토리, 상위 디렉토리, 사용자 설정 디렉토리에서 어떤 설정 파일도 읽지 않는다.
UV_NO_ENV_FILE¶
uv run 커맨드를 실행할 때 .env 파일을 무시한다.
UV_NO_INSTALLER_METADATA¶
uv 설치 프로그램 메타데이터 파일(예: INSTALLER, REQUESTED, direct_url.json)을 site-packages의 .dist-info 디렉토리에 쓰지 않도록 설정한다.
UV_NO_PROGRESS¶
--no-progress 커맨드라인 인수와 동일한 기능을 한다. 모든 진행 상황 출력을 비활성화한다. 예를 들어 스피너와 진행률 표시줄이 표시되지 않는다.
UV_NO_SYNC¶
--no-sync 커맨드라인 인수와 동일하다. 이 값을 설정하면 uv는 환경 업데이트를 건너뛴다.
UV_NO_VERIFY_HASHES¶
--no-verify-hashes 인자와 동일한 기능을 한다. requirements.txt 파일에 대한 해시 검증을 비활성화한다.
UV_NO_WRAP¶
진단 메시지의 줄 바꿈을 비활성화할 때 사용한다.
UV_OFFLINE¶
--offline 커맨드라인 인자와 동일한 기능을 한다. 이 값을 설정하면 uv가 네트워크 접근을 비활성화한다.
UV_OVERRIDE¶
--override 커맨드라인 인자와 동일한 기능을 한다. 이 값이 설정되면, uv는 해당 파일을 오버라이드 파일로 사용한다. 여러 파일을 공백으로 구분하여 지정할 수 있다.
UV_PRERELEASE¶
--prerelease 커맨드라인 인수와 동일한 기능을 한다. 예를 들어, 이 값을 allow로 설정하면 uv는 모든 의존성에 대해 프리릴리즈 버전을 허용한다.
UV_PREVIEW¶
--preview 인자와 동일한 기능을 한다. 프리뷰 모드를 활성화한다.
UV_PROJECT_ENVIRONMENT¶
프로젝트 가상 환경으로 사용할 디렉토리의 경로를 지정한다.
자세한 내용은 프로젝트 문서를 참고한다.
UV_PUBLISH_CHECK_URL¶
인덱스에 이미 파일이 존재하는 경우 업로드하지 않는다. 이 값은 인덱스의 URL을 나타낸다.
UV_PUBLISH_INDEX¶
uv publish 명령어에서 --index 커맨드라인 인자와 동일한 기능을 한다. 이 값이 설정되면, uv는 퍼블리싱을 위해 설정된 인덱스 이름을 사용한다.
UV_PUBLISH_PASSWORD¶
uv publish 명령어에서 --password 인자와 동일한 역할을 한다. 이 값을 설정하면, uv는 패키지 배포 시 해당 비밀번호를 사용한다.
UV_PUBLISH_TOKEN¶
uv publish 명령어에서 --token 인자와 동일한 역할을 한다. 이 값을 설정하면, uv는 __token__ 사용자 이름과 함께 이 토큰을 사용해 패키지를 게시한다.
UV_PUBLISH_URL¶
--publish-url 커맨드라인 인자와 동일한 기능을 한다. uv publish 명령어와 함께 사용할 인덱스의 업로드 엔드포인트 URL을 지정한다.
UV_PUBLISH_USERNAME¶
uv publish 커맨드라인 인수에서 --username과 동일한 역할을 한다. 이 값을 설정하면, uv는 패키지 배포 시 해당 사용자 이름을 사용한다.
UV_PYPY_INSTALL_MIRROR¶
관리되는 PyPy 설치 파일은 python.org에서 다운로드한다.
이 변수를 미러 URL로 설정하면 PyPy 설치 파일을 다른 소스에서 가져올 수 있다. 제공된 URL은 https://downloads.python.org/pypy를 대체한다. 예를 들어, https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2와 같은 URL에서 https://downloads.python.org/pypy 부분이 변경된다. file:// URL 스키마를 사용하면 로컬 디렉터리에서 배포 파일을 읽을 수 있다.
UV_PYTHON¶
--python 커맨드라인 인자와 동일한 기능을 한다. 경로를 설정하면 uv는 모든 작업에 이 Python 인터프리터를 사용한다.
UV_PYTHON_BIN_DIR¶
설치된 Python 실행 파일에 대한 링크를 배치할 디렉토리를 지정한다.
UV_PYTHON_DOWNLOADS¶
python-downloads 설정과 동일하며, 비활성화 시 --no-python-downloads 옵션에 해당한다. uv가 Python 다운로드를 허용할지 여부를 결정한다.
UV_PYTHON_INSTALL_DIR¶
관리되는 Python 설치를 저장할 디렉토리를 지정한다.
UV_PYTHON_INSTALL_MIRROR¶
Astral의 python-build-standalone 프로젝트에서 관리되는 Python 설치 파일을 다운로드한다.
이 변수를 미러 URL로 설정하면 Python 설치 파일을 다른 소스에서 가져올 수 있다. 제공된 URL은 https://github.com/astral-sh/python-build-standalone/releases/download를 대체한다. 예를 들어, https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz와 같은 URL에서 이 변수를 사용할 수 있다. file:// URL 스키마를 사용하면 로컬 디렉토리에서 배포 파일을 읽을 수도 있다.
UV_PYTHON_PREFERENCE¶
--python-preference 커맨드라인 인자와 동일한 기능을 한다. uv가 시스템 Python 버전을 선호할지, 아니면 관리되는 Python 버전을 선호할지를 결정한다.
UV_REQUEST_TIMEOUT¶
HTTP 요청에 대한 타임아웃(초 단위)을 설정한다. UV_HTTP_TIMEOUT과 동일한 기능을 제공한다.
UV_REQUIRE_HASHES¶
--require-hashes 커맨드라인 인자와 동일한 기능을 한다. 이 값을 true로 설정하면, uv는 모든 의존성에 대해 요구사항 파일에 해시값이 명시되어 있어야 한다.
UV_RESOLUTION¶
--resolution 커맨드라인 인자와 동일한 기능을 한다. 예를 들어, lowest-direct로 설정하면 uv는 모든 직접 의존성의 가장 낮은 호환 버전을 설치한다.
UV_SYSTEM_PYTHON¶
이 환경 변수는 --system 커맨드라인 인자와 동일한 기능을 한다. true로 설정하면 uv는 시스템 PATH에서 발견된 첫 번째 Python 인터프리터를 사용한다.
경고: UV_SYSTEM_PYTHON=true는 주로 지속적 통합(CI)이나 컨테이너 환경에서 사용하기 위한 목적으로 설계되었다. 시스템 Python을 수정하면 예기치 않은 동작이 발생할 수 있으므로 주의해서 사용해야 한다.
UV_TOOL_BIN_DIR¶
도구 실행 파일을 설치할 "bin" 디렉토리를 지정한다.
UV_TOOL_DIR¶
UV_TOOL_DIR은 uv가 관리하는 도구들을 저장하는 디렉터리를 지정한다.
UV_UNMANAGED_INSTALL¶
CI와 같은 임시 환경에서 uv를 특정 경로에 설치할 때 사용한다. 이 옵션은 설치 프로그램이 쉘 프로필이나 환경 변수를 수정하지 못하도록 방지한다.
UV_VENV_SEED¶
uv venv로 생성한 가상 환경에 시드 패키지(pip, setuptools, wheel 중 하나 이상)를 설치한다.
Python 3.12 이상 환경에서는 setuptools와 wheel이 포함되지 않는다.
외부에서 정의된 변수¶
uv는 다음과 같이 외부에서 정의된 환경 변수를 읽는다:
ACTIONS_ID_TOKEN_REQUEST_TOKEN¶
uv publish를 통해 신뢰할 수 있는 게시를 위해 사용된다. OIDC 요청 토큰을 포함한다.
ACTIONS_ID_TOKEN_REQUEST_URL¶
uv publish를 통해 신뢰할 수 있는 게시를 수행할 때 사용된다. OIDC 토큰 URL을 포함한다.
ALL_PROXY¶
모든 네트워크 요청에 대한 일반적인 프록시 설정이다.
BASH_VERSION¶
Bash 쉘 사용 여부를 확인하는 데 사용한다.
CLICOLOR_FORCE¶
CLICOLOR_FORCE는 anstyle을 통해 색상을 제어하는 데 사용한다.
COLUMNS¶
터미널의 줄바꿈에 사용되는 너비를 재정의한다. 이 변수는 uv에서 직접 읽지 않는다.
이 변수는 ncurses(3x) 등에서 설명된 준표준 변수이다.
CONDA_DEFAULT_ENV¶
활성화된 Conda 환경이 기본 환경인지 아닌지를 판단하는 데 사용한다.
CONDA_PREFIX¶
Conda 환경이 활성화되었는지 확인하는 데 사용된다.
FISH_VERSION¶
Fish 쉘 사용 여부를 감지한다.
FORCE_COLOR¶
터미널 지원 여부와 상관없이 강제로 색상 출력을 활성화한다.
자세한 내용은 force-color.org를 참고한다.
GITHUB_ACTIONS¶
uv publish를 통해 신뢰할 수 있는 배포에 사용된다.
HOME¶
표준 HOME 환경 변수
HTTPS_PROXY¶
HTTPS 요청을 위한 프록시 설정이다.
HTTP_PROXY¶
HTTP 요청을 위한 프록시 설정이다.
HTTP_TIMEOUT¶
HTTP 요청에 대한 타임아웃(초 단위)을 설정한다. UV_HTTP_TIMEOUT과 동일한 기능을 제공한다.
INSTALLER_NO_MODIFY_PATH¶
uv를 독립 실행형 설치 프로그램과 self update 기능으로 설치할 때 PATH 환경 변수를 수정하지 않는다.
JPY_SESSION_NAME¶
Jupyter 노트북 내에서 실행 중인지 감지하는 데 사용한다.
KSH_VERSION¶
Ksh 셸 사용 여부를 감지하는 데 사용한다.
LOCALAPPDATA¶
Microsoft Store에 설치된 Python을 찾는 데 사용한다.
MACOSX_DEPLOYMENT_TARGET¶
--python-platform macos 및 관련 옵션과 함께 사용하여 배포 타겟(즉, 지원하는 최소 macOS 버전)을 설정한다.
기본값은 12.0으로, 작성 시점에서 가장 최신이면서 지원이 종료되지 않은 macOS 버전이다.
NETRC¶
.netrc 파일의 위치를 설정한다.
NO_COLOR¶
색상 출력을 비활성화한다. (FORCE_COLOR보다 우선 적용됨)
자세한 내용은 no-color.org를 참고한다.
NU_VERSION¶
NuShell 사용 여부를 감지한다.
PAGER¶
표준 PAGER POSIX 환경 변수. uv가 적절한 페이저를 구성할 때 사용한다.
PATH¶
표준 PATH 환경 변수.
PROMPT¶
Windows 명령 프롬프트(Command Prompt) 사용 여부를 감지하는 데 사용한다. (PowerShell과 구별하기 위해)
PWD¶
표준 PWD POSIX 환경 변수.
PYC_INVALIDATION_MODE¶
--compile 옵션과 함께 실행할 때 사용할 검증 모드를 설정한다.
자세한 내용은 PycInvalidationMode 문서를 참고한다.
PYTHONPATH¶
Python 모듈 검색 경로에 디렉토리를 추가한다 (예: PYTHONPATH=/path/to/modules).
RUST_LOG¶
이 환경 변수를 설정하면 uv는 --verbose 출력에 대한 로그 레벨로 이 값을 사용한다. tracing_subscriber 크레이트와 호환되는 모든 필터를 허용한다.
예를 들어:
RUST_LOG=uv=debug는 커맨드라인에--verbose를 추가하는 것과 동일하다.RUST_LOG=trace는 트레이스 레벨 로깅을 활성화한다.
자세한 내용은 tracing 문서를 참고한다.
RUST_MIN_STACK¶
이 설정은 uv에서 사용하는 스택 크기를 조정한다. 값은 바이트 단위로 지정하며, 기본값은 일반적으로 2MB(2097152)이다. 일반적인 RUST_MIN_STACK의 의미와 달리, 이 설정은 메인 스레드의 스택 크기에도 영향을 미칠 수 있다. 윈도우의 실제 메인 스레드가 1MB로 제한되어 있기 때문에, 이를 해결하기 위해 별도의 main2 스레드를 생성하기 때문이다. 이 스레드의 크기는 max(RUST_MIN_STACK, 4MB)로 설정된다.
SHELL¶
표준 SHELL POSIX 환경 변수.
SSL_CERT_FILE¶
SSL 연결에 사용할 커스텀 인증서 번들 파일 경로를 지정한다.
SSL_CLIENT_CERT¶
이 값이 설정되면, uv는 mTLS 인증을 위해 이 파일을 사용한다. 이 파일은 PEM 포맷으로 된 인증서와 개인 키를 모두 포함한 단일 파일이어야 한다.
SYSTEMDRIVE¶
Windows 시스템에서 시스템 수준 설정 디렉터리의 경로를 나타낸다.
TRACING_DURATIONS_FILE¶
tracing-durations-export 기능을 통해 트레이싱 지속 시간 파일을 생성할 때 사용한다.
UV¶
uv를 실행하는 데 사용된 바이너리의 경로를 나타낸다.
이 값은 uv에 의해 생성된 모든 하위 프로세스로 전파된다.
실행 파일이 심볼릭 링크를 통해 호출된 경우, 일부 플랫폼에서는 심볼릭 링크의 경로를 반환하고, 다른 플랫폼에서는 심볼릭 링크의 대상 경로를 반환한다.
보안 고려 사항에 대해서는 https://doc.rust-lang.org/std/env/fn.current_exe.html#security를 참고한다.
VIRTUAL_ENV¶
가상 환경이 활성화되었는지 확인하는 데 사용된다.
VIRTUAL_ENV_DISABLE_PROMPT¶
가상 환경을 활성화하기 전에 이 값을 1로 설정하면, 터미널 프롬프트에 가상 환경 이름이 추가되지 않는다.
XDG_BIN_HOME¶
실행 파일이 설치되는 디렉터리의 경로를 나타낸다.
XDG_CACHE_HOME¶
유닉스 시스템에서 캐시 디렉터리의 경로를 나타낸다.
XDG_CONFIG_DIRS¶
유닉스 시스템에서 시스템 수준의 설정 디렉터리 경로를 나타낸다.
XDG_CONFIG_HOME¶
유닉스 시스템에서 사용자 수준의 설정 디렉터리 경로를 나타낸다.
XDG_DATA_HOME¶
Python 설치와 도구를 관리하기 위한 디렉터리 경로.
ZDOTDIR¶
Zsh을 사용할 때 어떤 .zshenv 파일을 사용할지 결정한다.
ZSH_VERSION¶
Zsh 셸 사용 여부를 감지하는 데 사용한다.