CLI 참조¶

uv¶

매우 빠른 Python 패키지 관리자.

사용법

uv [OPTIONS] <COMMAND>

커맨드

uv run: 커맨드나 스크립트 실행
uv init: 새 프로젝트 생성
uv add: 프로젝트에 의존성 추가
uv remove: 프로젝트에서 의존성 제거
uv sync: 프로젝트 환경 업데이트
uv lock: 프로젝트의 lockfile 업데이트
uv export: 프로젝트의 lockfile을 다른 형식으로 내보내기
uv tree: 프로젝트의 의존성 트리 표시
uv tool: Python 패키지가 제공하는 커맨드 실행 및 설치
uv python: Python 버전 및 설치 관리
uv pip: pip 호환 인터페이스로 Python 패키지 관리
uv venv: 가상 환경 생성
uv build: Python 패키지를 소스 배포판과 휠로 빌드
uv publish: 배포판을 인덱스에 업로드
uv cache: uv의 캐시 관리
uv self: uv 실행 파일 관리
uv version: uv 버전 표시
uv help: 커맨드에 대한 문서 표시

uv run¶

커맨드나 스크립트를 실행한다. Python 환경에서 실행되도록 보장한다.

.py로 끝나는 파일이나 HTTP(S) URL을 사용하면, 해당 파일을 스크립트로 간주하여 Python 인터프리터로 실행한다. 예를 들어 uv run file.py는 uv run python file.py와 동일하다. URL의 경우, 스크립트를 임시로 다운로드한 후 실행한다. 스크립트에 인라인 의존성 메타데이터가 포함되어 있으면, 격리된 임시 환경에 설치한다. -를 사용하면 입력을 stdin에서 읽어 Python 스크립트로 처리한다.

프로젝트 내에서 사용하면, 프로젝트 환경을 생성하거나 업데이트한 후 커맨드를 실행한다.

프로젝트 외부에서 사용하면, 현재 디렉토리나 상위 디렉토리에서 가상 환경을 찾아 해당 환경에서 커맨드를 실행한다. 가상 환경이 없으면, 발견된 인터프리터의 환경에서 실행한다.

커맨드(또는 스크립트) 뒤에 오는 인수는 uv의 인수로 해석되지 않는다. uv의 모든 옵션은 커맨드 앞에 제공해야 한다. 예를 들어 uv run --verbose foo와 같다. 명확성을 위해 --를 사용해 커맨드와 uv 옵션을 구분할 수 있다. 예를 들어 uv run --python 3.12 -- python과 같다.

사용법

uv run [OPTIONS] [COMMAND]

옵션

--active

프로젝트의 가상 환경보다 활성 가상 환경을 우선한다.

프로젝트 가상 환경이 활성 상태이거나 활성 가상 환경이 없으면 이 옵션은 영향을 미치지 않는다.

--all-extras

모든 선택적 의존성을 포함한다.

선택적 의존성은 `pyproject.toml`의 `project.optional-dependencies`에 정의된다.

이 옵션은 프로젝트 내에서만 사용할 수 있다.

--all-groups

모든 의존성 그룹을 포함한다.

`--no-group`을 사용해 특정 그룹을 제외할 수 있다.

--all-packages

모든 워크스페이스 멤버가 설치된 상태로 커맨드를 실행한다.

워크스페이스 환경(`.venv`)이 업데이트되어 모든 워크스페이스 멤버를 포함한다.

`--extra`, `--group` 또는 관련 옵션을 통해 지정된 추가 기능이나 그룹은 모든 워크스페이스 멤버에 적용된다.

--allow-insecure-host allow-insecure-host

호스트에 대한 안전하지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: `localhost`), 호스트-포트 쌍(예: `localhost:8080`), 또는 URL(예: `https://localhost`)을 입력받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소와 비교해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크와 소스에서만 사용해야 한다.

`UV_INSECURE_HOST` 환경 변수로도 설정할 수 있다.

--cache-dir cache-dir

캐시 디렉토리 경로.

기본값은 macOS와 Linux에서는 `$XDG_CACHE_HOME/uv` 또는 `$HOME/.cache/uv`, Windows에서는 `%LOCALAPPDATA%\uv\cache`이다.

캐시 디렉토리의 위치를 확인하려면 `uv cache dir`을 실행한다.

`UV_CACHE_DIR` 환경 변수로도 설정할 수 있다.

--color color-choice

출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:

auto: 출력이 색상을 지원하는 터미널이나 TTY로 갈 때만 색상 출력을 활성화
always: 환경과 상관없이 항상 색상 출력을 활성화
never: 색상 출력을 비활성화

--compile-bytecode

설치 후 Python 파일을 바이트코드로 컴파일한다.

기본적으로 uv는 Python(`.py`) 파일을 바이트코드(`__pycache__/*.pyc`)로 컴파일하지 않는다. 대신 모듈을 처음 임포트할 때 지연 컴파일을 수행한다. CLI 애플리케이션이나 Docker 컨테이너와 같이 시작 시간이 중요한 경우, 이 옵션을 활성화해 설치 시간을 늘리는 대신 시작 시간을 단축할 수 있다.

활성화하면 uv는 전체 site-packages 디렉토리(현재 작업으로 수정되지 않은 패키지 포함)를 일관성 있게 처리한다. pip와 마찬가지로 오류도 무시한다.

`UV_COMPILE_BYTECODE` 환경 변수로도 설정할 수 있다.

--config-file config-file

설정에 사용할 `uv.toml` 파일 경로.

uv 설정은 `pyproject.toml` 파일에 포함할 수 있지만, 이 경우는 허용되지 않는다.

`UV_CONFIG_FILE` 환경 변수로도 설정할 수 있다.

--config-setting, -C config-setting

PEP 517 빌드 백엔드에 전달할 설정. `KEY=VALUE` 쌍으로 지정

--default-index default-index

기본 패키지 인덱스 URL (기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소나 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 지정된 인덱스는 `--index` 플래그로 지정된 모든 인덱스보다 낮은 우선순위를 가진다.

`UV_DEFAULT_INDEX` 환경 변수로도 설정할 수 있다.

--directory directory

커맨드를 실행하기 전에 주어진 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해결된다.

프로젝트 루트 디렉토리만 변경하려면 `--project`를 참조한다.

--env-file env-file

`.env` 파일에서 환경 변수를 로드한다.

여러 번 제공할 수 있으며, 이후 파일은 이전 파일에 정의된 값을 덮어쓴다.

`UV_ENV_FILE` 환경 변수로도 설정할 수 있다.

--exact

정확한 동기화를 수행해 불필요한 패키지를 제거한다.

활성화하면 uv는 환경에서 불필요한 패키지를 제거한다. 기본적으로 `uv run`은 요구 사항을 충족하기 위한 최소한의 변경만 수행한다.

--exclude-newer exclude-newer

주어진 날짜 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 타임스탬프(예: `2006-12-02T02:07:43Z`)나 시스템의 시간대에 맞는 로컬 날짜(예: `2006-12-02`)를 입력받는다.

`UV_EXCLUDE_NEWER` 환경 변수로도 설정할 수 있다.

--extra extra

지정된 추가 기능 이름에 해당하는 선택적 의존성을 포함한다.

여러 번 제공할 수 있다.

선택적 의존성은 `pyproject.toml`의 `project.optional-dependencies`에 정의된다.

이 옵션은 프로젝트 내에서만 사용할 수 있다.

--extra-index-url extra-index-url

(사용 중단: `--index` 대신 사용) `--index-url` 외에 사용할 추가 패키지 인덱스 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소나 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 제공된 모든 인덱스는 `--index-url`로 지정된 인덱스(기본값은 PyPI)보다 높은 우선순위를 가진다. 여러 `--extra-index-url` 플래그를 제공하면, 이전 값이 우선순위를 가진다.

`UV_EXTRA_INDEX_URL` 환경 변수로도 설정할 수 있다.

--find-links, -f find-links

레지스트리 인덱스 외에 후보 배포판을 검색할 위치.

경로를 입력하면, 대상은 최상위에 휠 파일(`.whl`)이나 소스 배포판(예: `.tar.gz` 또는 `.zip`)이 포함된 디렉토리여야 한다.

URL을 입력하면, 페이지에 위 형식을 준수하는 패키지 파일 링크가 평면적으로 나열되어 있어야 한다.

`UV_FIND_LINKS` 환경 변수로도 설정할 수 있다.

--fork-strategy fork-strategy

여러 Python 버전과 플랫폼에서 주어진 패키지의 여러 버전을 선택할 때 사용할 전략.

기본적으로 uv는 지원되는 Python 버전(`requires-python`)에 대해 각 패키지의 최신 버전을 선택하면서, 플랫폼 간 선택된 버전 수를 최소화한다.

`fewest`를 선택하면, uv는 각 패키지에 대해 선택된 버전 수를 최소화하고, 지원되는 Python 버전이나 플랫폼 범위가 더 넓은 이전 버전을 선호한다.

`UV_FORK_STRATEGY` 환경 변수로도 설정할 수 있다.

가능한 값:

fewest: 각 패키지에 대해 선택된 버전 수를 최소화. 지원되는 Python 버전이나 플랫폼 범위가 더 넓은 이전 버전을 선호
requires-python: 지원되는 Python 버전에 대해 각 패키지의 최신 버전을 선택

--frozen

`uv.lock` 파일을 업데이트하지 않고 실행한다.

lockfile이 최신 상태인지 확인하는 대신, lockfile에 있는 버전을 기준으로 사용한다. lockfile이 없으면 uv는 오류와 함께 종료한다. `pyproject.toml`에 lockfile에 아직 포함되지 않은 의존성 변경 사항이 있으면, 해당 의존성은 환경에 포함되지 않는다.

`UV_FROZEN` 환경 변수로도 설정할 수 있다.

--group group

지정된 의존성 그룹을 포함한다.

여러 번 제공할 수 있다.

--gui-script

주어진 경로를 Python GUI 스크립트로 실행한다.

`--gui-script`를 사용하면 경로를 PEP 723 스크립트로 파싱하고, 확장자와 상관없이 `pythonw.exe`로 실행한다. Windows에서만 사용할 수 있다.

--help, -h

이 커맨드에 대한 간단한 도움말을 표시

--index index

의존성을 해결할 때 사용할 URL. 기본 인덱스 외에 추가로 사용.

PEP 503(단순 저장소 API)을 준수하는 저장소나 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 제공된 모든 인덱스는 `--default-index`로 지정된 인덱스(기본값은 PyPI)보다 높은 우선순위를 가진다. 여러 `--index` 플래그를 제공하면, 이전 값이 우선순위를 가진다.

`UV_INDEX` 환경 변수로도 설정할 수 있다.

--index-strategy index-strategy

여러 인덱스 URL에 대해 해결할 때 사용할 전략.

기본적으로 uv는 주어진 패키지가 사용 가능한 첫 번째 인덱스에서 멈추고, 해당 첫 번째 인덱스에 있는 것만 해결한다(`first-index`). 이는 공격자가 대체 인덱스에 동일한 이름의 악성 패키지를 업로드할 수 있는 "의존성 혼동" 공격을 방지한다.

`UV_INDEX_STRATEGY` 환경 변수로도 설정할 수 있다.

가능한 값:

first-index: 주어진 패키지 이름에 대해 첫 번째로 일치하는 인덱스의 결과만 사용
unsafe-first-match: 모든 인덱스에서 모든 패키지 이름을 검색하고, 첫 번째 인덱스의 버전을 모두 소진한 후 다음 인덱스로 이동
unsafe-best-match: 모든 인덱스에서 모든 패키지 이름을 검색하고, "최고" 버전을 선호. 패키지 버전이 여러 인덱스에 있으면 첫 번째 인덱스의 항목만 확인

--index-url, -i index-url

(사용 중단: `--default-index` 대신 사용) Python 패키지 인덱스 URL (기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소나 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 지정된 인덱스는 `--extra-index-url` 플래그로 지정된 모든 인덱스보다 낮은 우선순위를 가진다.

`UV_INDEX_URL` 환경 변수로도 설정할 수 있다.

--isolated

격리된 가상 환경에서 커맨드를 실행한다.

일반적으로 프로젝트 환경은 성능을 위해 재사용된다. 이 옵션은 프로젝트에 대해 새로운 환경을 강제로 사용해 의존성과 요구 사항 선언 간의 엄격한 격리를 강제한다.

프로젝트에 대해 편집 가능한 설치가 여전히 사용된다.

`--with` 또는 `--with-requirements`와 함께 사용하면, 추가 의존성은 여전히 두 번째 환경에 계층화된다.

--keyring-provider keyring-provider

인덱스 URL에 대한 인증을 위해 `keyring` 사용을 시도한다.

현재 `--keyring-provider subprocess`만 지원되며, 이는 uv가 `keyring` CLI를 사용해 인증을 처리하도록 설정한다.

기본값은 `disabled`이다.

`UV_KEYRING_PROVIDER` 환경 변수로도 설정할 수 있다.

가능한 값:

disabled: 자격 증명 조회에 keyring을 사용하지 않음
subprocess: `keyring` 커맨드를 사용해 자격 증명 조회

--link-mode link-mode

글로벌 캐시에서 패키지를 설치할 때 사용할 방법.

기본값은 macOS에서는 `clone`(Copy-on-Write), Linux와 Windows에서는 `hardlink`이다.

`UV_LINK_MODE` 환경 변수로도 설정할 수 있다.

가능한 값:

clone: 휠에서 `site-packages` 디렉토리로 패키지를 복제(Copy-on-Write)
copy: 휠에서 `site-packages` 디렉토리로 패키지를 복사
hardlink: 휠에서 `site-packages` 디렉토리로 패키지를 하드 링크
symlink: 휠에서 `site-packages` 디렉토리로 패키지를 심볼릭 링크

--locked

`uv.lock` 파일이 변경되지 않을 것임을 단언한다.

lockfile이 최신 상태여야 한다. lockfile이 없거나 업데이트가 필요하면 uv는 오류와 함께 종료한다.

`UV_LOCKED` 환경 변수로도 설정할 수 있다.

--module, -m

Python 모듈을 실행한다.

`python -m `과 동일하다.

--native-tls

플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 `webpki-roots` 크레이트에서 인증서를 로드한다. `webpki-roots`는 Mozilla의 신뢰할 수 있는 루트 집합이며, uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 기업 신뢰 루트(예: 필수 프록시)에 의존하는 경우, 플랫폼의 기본 인증서 저장소를 사용하고 싶을 수 있다.

`UV_NATIVE_TLS` 환경 변수로도 설정할 수 있다.

--no-binary

미리 빌드된 휠을 설치하지 않는다.

주어진 패키지는 소스에서 빌드되고 설치된다. 리졸버는 여전히 가능하면 미리 빌드된 휠을 사용해 패키지 메타데이터를 추출한다.

`UV_NO_BINARY` 환경 변수로도 설정할 수 있다.

--no-binary-package no-binary-package

특정 패키지에 대해 미리 빌드된 휠을 설치하지 않는다.

`UV_NO_BINARY_PACKAGE` 환경 변수로도 설정할 수 있다.

--no-build

소스 배포판을 빌드하지 않는다.

활성화하면 리졸빙은 임의의 Python 코드를 실행하지 않는다. 이미 빌드된 소스 배포판의 캐시된 휠이 재사용되지만, 배포판 빌드가 필요한 작업은 오류와 함께 종료된다.

--no-build-isolation

소스 배포판 빌드 시 격리를 비활성화한다.

PEP 518에 의해 지정된 빌드 의존성이 이미 설치되어 있다고 가정한다.

`UV_NO_BUILD_ISOLATION` 환경 변수로도 설정할 수 있다.

--no-build-isolation-package no-build-isolation-package

특정 패키지에 대해 소스 배포판 빌드 시 격리를 비활성화한다.

패키지의 빌드 의존성이 PEP 518에 의해 이미 설치되어 있다고 가정한다.

--no-build-package no-build-package

특정 패키지에 대해 소스 배포판을 빌드하지 않는다.

--no-cache, -n

캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

`UV_NO_CACHE` 환경 변수로도 설정할 수 있다.

--no-config

설정 파일(`pyproject.toml`, `uv.toml`)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리, 또는 사용자 설정 디렉토리에서 검색된다.

`UV_NO_CONFIG` 환경 변수로도 설정할 수 있다.

--no-default-groups

기본 의존성 그룹을 무시한다.

uv는 기본적으로 `tool.uv.default-groups`에 정의된 그룹을 포함한다. 이 옵션은 해당 기능을 비활성화하지만, `--group`을 통해 특정 그룹을 여전히 포함할 수 있다.

--no-dev

개발 의존성 그룹을 비활성화한다.

이 옵션은 `--no-group dev`의 별칭이다. 모든 기본 그룹을 비활성화하려면 `--no-default-groups`를 참조한다.

이 옵션은 프로젝트 내에서만 사용할 수 있다.

--no-editable

프로젝트나 워크스페이스 멤버를 포함한 모든 편집 가능한 의존성을 편집 불가능하게 설치한다.

--no-env-file

`.env` 파일에서 환경 변수를 읽지 않는다.

`UV_NO_ENV_FILE` 환경 변수로도 설정할 수 있다.

--no-extra no-extra

`--all-extras`가 제공된 경우, 지정된 선택적 의존성을 제외한다.

여러 번 제공할 수 있다.

--no-group no-group

지정된 의존성 그룹을 비활성화한다.

이 옵션은 항상 기본 그룹, `--all-groups`, `--group`보다 우선한다.

여러 번 제공할 수 있다.

--no-index

레지스트리 인덱스(예: PyPI)를 무시하고, 직접 URL 의존성과 `--find-links`로 제공된 것만 사용한다.

--no-progress

모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄.

`UV_NO_PROGRESS` 환경 변수로도 설정할 수 있다.

--no-project

프로젝트나 워크스페이스를 검색하지 않는다.

현재 디렉토리와 상위 디렉토리에서 프로젝트를 검색하는 대신, `--with` 요구 사항으로 채워진 격리된 임시 환경에서 실행한다.

활성 가상 환경이 있거나 현재 디렉토리나 상위 디렉토리에서 발견되면, 프로젝트나 워크스페이스가 없는 것처럼 해당 환경이 사용된다.

--no-python-downloads

Python의 자동 다운로드를 비활성화한다.

--no-sources

`tool.uv.sources` 테이블을 무시하고 의존성을 해결한다. 워크스페이스, Git, URL, 또는 로컬 경로 소스를 사용하는 대신, 표준을 준수하고 게시 가능한 패키지 메타데이터에 대해 잠금을 사용한다.

--no-sync

가상 환경 동기화를 하지 않는다.

`--frozen`을 암시한다. 프로젝트 의존성이 무시되므로(즉, 환경이 동기화되지 않으므로 lockfile이 업데이트되지 않음).

`UV_NO_SYNC` 환경 변수로도 설정할 수 있다.

--offline

네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

`UV_OFFLINE` 환경 변수로도 설정할 수 있다.

--only-dev

개발 의존성 그룹만 포함한다.

프로젝트와 그 의존성은 제외된다.

이 옵션은 `--only-group dev`의 별칭이다. `--no-default-groups`를 암시한다.

--only-group only-group

지정된 의존성 그룹만 포함한다.

프로젝트와 그 의존성은 제외된다.

여러 번 제공할 수 있다. `--no-default-groups`를 암시한다.

--package package

워크스페이스의 특정 패키지에서 커맨드를 실행한다.

워크스페이스 멤버가 없으면 uv는 오류와 함께 종료한다.

--prerelease prerelease

프리릴리스 버전을 고려할 때 사용할 전략.

기본적으로 uv는 프리릴리스만 출시하는 패키지와 선언된 지정자에 명시적 프리릴리스 마커가 포함된 일차 의존성에 대해 프리릴리스를 허용한다(`if-necessary-or-explicit`).

`UV_PRERELEASE` 환경 변수로도 설정할 수 있다.

가능한 값:

disallow: 모든 프리릴리스 버전을 허용하지 않음
allow: 모든 프리릴리스 버전을 허용
if-necessary: 패키지의 모든 버전이 프리릴리스인 경우 프리릴리스 버전을 허용
explicit: 버전 요구 사항에 명시적 프리릴리스 마커가 포함된 일차 패키지에 대해 프리릴리스 버전을 허용
if-necessary-or-explicit: 패키지의 모든 버전이 프리릴리스인 경우, 또는 패키지의 버전 요구 사항에 명시적 프리릴리스 마커가 포함된 경우 프리릴리스 버전을 허용

--project project

주어진 프로젝트 디렉토리 내에서 커맨드를 실행한다.

모든 `pyproject.toml`, `uv.toml`, `.python-version` 파일은 프로젝트 루트에서 디렉토리 트리를 올라가며 검색되며, 프로젝트의 가상 환경(`.venv`)도 마찬가지이다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해결된다.

작업 디렉토리를 완전히 변경하려면 `--directory`를 참조한다.

이 설정은 `uv pip` 인터페이스에서 사용할 때 영향을 미치지 않는다.

--python, -p python

실행 환경에 사용할 Python 인터프리터.

발견된 환경이 인터프리터 요청을 충족하면 해당 환경이 사용된다.

지원되는 요청 형식을 확인하려면 uv python을 참조한다.

`UV_PYTHON` 환경 변수로도 설정할 수 있다.

--python-preference python-preference

uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 여부.

기본적으로 uv는 관리하는 Python 버전을 선호한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션은 시스템 Python 설치를 우선하거나 무시할 수 있게 한다.

`UV_PYTHON_PREFERENCE` 환경 변수로도 설정할 수 있다.

가능한 값:

only-managed: 관리되는 Python 설치만 사용. 시스템 Python 설치를 사용하지 않음
managed: 시스템 Python 설치보다 관리되는 Python 설치를 우선
system: 관리되는 Python 설치보다 시스템 Python 설치를 우선
only-system: 시스템 Python 설치만 사용. 관리되는 Python 설치를 사용하지 않음

--quiet, -q

어떤 출력도 표시하지 않음

--refresh

모든 캐시 데이터를 새로 고침

--refresh-package refresh-package

특정 패키지의 캐시 데이터를 새로 고침

--reinstall

이미 설치되어 있더라도 모든 패키지를 다시 설치. `--refresh`를 암시

--reinstall-package reinstall-package

이미 설치되어 있더라도 특정 패키지를 다시 설치. `--refresh-package`를 암시

--resolution resolution

주어진 패키지 요구 사항에 대해 여러 호환 버전을 선택할 때 사용할 전략.

기본적으로 uv는 각 패키지의 최신 호환 버전을 사용한다(`highest`).

`UV_RESOLUTION` 환경 변수로도 설정할 수 있다.

가능한 값:

highest: 각 패키지의 최신 호환 버전을 해결
lowest: 각 패키지의 최저 호환 버전을 해결
lowest-direct: 직접 의존성의 최저 호환 버전을 해결하고, 전이 의존성의 최신 호환 버전을 해결

--script, -s

주어진 경로를 Python 스크립트로 실행한다.

`--script`를 사용하면 경로를 PEP 723 스크립트로 파싱하고, 확장자와 상관없이 실행한다.

--upgrade, -U

패키지 업그레이드를 허용하고, 기존 출력 파일에 고정된 버전을 무시. `--refresh`를 암시

--upgrade-package, -P upgrade-package

특정 패키지의 업그레이드를 허용하고, 기존 출력 파일에 고정된 버전을 무시. `--refresh-package`를 암시

--verbose, -v

자세한 출력을 사용.

`RUST_LOG` 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V

uv 버전을 표시

--with with

주어진 패키지가 설치된 상태로 커맨드를 실행한다.

프로젝트 내에서 사용하면, 이 의존성은 프로젝트 환경 위에 별도의 임시 환경에 계층화된다. 이 의존성은 프로젝트에 의해 지정된 의존성과 충돌할 수 있다.

--with-editable with-editable

주어진 패키지를 편집 가능 모드로 설치한 상태로 커맨드를 실행한다.

프로젝트 내에서 사용하면, 이 의존성은 프로젝트 환경 위에 별도의 임시 환경에 계층화된다. 이 의존성은 프로젝트에 의해 지정된 의존성과 충돌할 수 있다.

--with-requirements with-requirements

주어진 `requirements.txt` 파일에 나열된 모든 패키지가 설치된 상태로 커맨드를 실행한다.

`--with`와 동일한 환경 의미론이 적용된다.

`pyproject.toml`, `setup.py`, 또는 `setup.cfg` 파일 사용은 허용되지 않는다.

uv init¶

새 프로젝트를 생성한다.

pyproject.toml 명세를 따른다.

대상 경로에 pyproject.toml이 이미 존재하면 uv는 오류와 함께 종료된다.

대상 경로의 상위 디렉터리 중 하나에서 pyproject.toml을 발견하면, 프로젝트는 상위 디렉터리의 작업 공간 멤버로 추가된다.

일부 프로젝트 상태는 필요할 때까지 생성되지 않는다. 예를 들어, 프로젝트 가상 환경(.venv)과 락 파일(uv.lock)은 첫 번째 동기화 시점에 지연 생성된다.

사용법

uv init [OPTIONS] [PATH]

인자

PATH

프로젝트/스크립트에 사용할 경로.

앱이나 라이브러리를 초기화할 때는 기본적으로 현재 작업 디렉터리를 사용한다. 스크립트를 초기화할 때는 필수로 지정해야 한다. 상대 경로와 절대 경로 모두 허용한다.

대상 경로의 상위 디렉터리 중 하나에서 pyproject.toml을 발견하면, --no-workspace를 제공하지 않는 한 프로젝트는 상위 디렉터리의 작업 공간 멤버로 추가된다.

옵션

--allow-insecure-host allow-insecure-host

호스트에 대한 안전하지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 안전한 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수를 통해 설정할 수도 있다.

--app

애플리케이션용 프로젝트를 생성한다.

--lib를 요청하지 않으면 기본 동작이다.

이 프로젝트 종류는 웹 서버, 스크립트, 커맨드라인 인터페이스를 위한 것이다.

기본적으로 애플리케이션은 Python 패키지로 빌드 및 배포할 목적이 아니다. PyPI를 통해 커맨드라인 인터페이스를 배포하려는 경우와 같이 배포 가능한 애플리케이션을 생성하려면 --package 옵션을 사용한다.

--author-from author-from

pyproject.toml의 authors 필드를 채운다.

기본적으로 uv는 일부 소스(예: Git)에서 작성자 정보를 추론하려고 시도한다(auto). Git 설정에서만 추론하려면 --author-from git을 사용한다. 작성자 정보를 추론하지 않으려면 --author-from none을 사용한다.

가능한 값:

auto: 일부 소스(예: Git)에서 자동으로 작성자 정보를 가져온다
git: Git 설정에서만 작성자 정보를 가져온다
none: 작성자 정보를 추론하지 않는다

--bare

pyproject.toml만 생성한다.

README.md, src/ 트리, .python-version 파일 등의 추가 파일 생성을 비활성화한다.

--build-backend build-backend

프로젝트에 사용할 빌드 백엔드를 초기화한다.

--package를 암시적으로 설정한다.

가능한 값:

hatch: hatchling을 프로젝트 빌드 백엔드로 사용한다
flit: flit-core을 프로젝트 빌드 백엔드로 사용한다
pdm: pdm-backend을 프로젝트 빌드 백엔드로 사용한다
setuptools: setuptools을 프로젝트 빌드 백엔드로 사용한다
maturin: maturin을 프로젝트 빌드 백엔드로 사용한다
scikit: scikit-build-core을 프로젝트 빌드 백엔드로 사용한다

--cache-dir cache-dir

캐시 디렉터리 경로.

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉터리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수를 통해 설정할 수도 있다.

--color color-choice

출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:

auto: 출력이 색상을 지원하는 터미널이나 TTY로 전송될 때만 색상 출력을 활성화한다
always: 감지된 환경에 관계없이 항상 색상 출력을 활성화한다
never: 색상 출력을 비활성화한다

--config-file config-file

구성에 사용할 uv.toml 파일 경로.

uv 구성은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수를 통해 설정할 수도 있다.

--description description

프로젝트 설명을 설정한다

--directory directory

명령 실행 전 주어진 디렉터리로 변경한다.

상대 경로는 주어진 디렉터리를 기준으로 해석된다.

프로젝트 루트 디렉터리만 변경하려면 --project를 참조한다.

--help, -h

이 명령에 대한 간단한 도움말을 표시한다

--lib

라이브러리용 프로젝트를 생성한다.

라이브러리는 Python 패키지로 빌드 및 배포할 목적의 프로젝트다.

--name name

프로젝트 이름.

기본값은 디렉터리 이름이다.

--native-tls

플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 세트이며, 이를 uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우, 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수를 통해 설정할 수도 있다.

--no-cache, -n

캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉터리를 사용한다

UV_NO_CACHE 환경 변수를 통해 설정할 수도 있다.

--no-config

구성 파일(pyproject.toml, uv.toml)을 탐색하지 않는다.

일반적으로 구성 파일은 현재 디렉터리, 상위 디렉터리, 또는 사용자 구성 디렉터리에서 탐색된다.

UV_NO_CONFIG 환경 변수를 통해 설정할 수도 있다.

--no-description

프로젝트 설명을 비활성화한다

--no-package

프로젝트를 Python 패키지로 빌드할 수 있도록 설정하지 않는다.

프로젝트에 [build-system]을 포함하지 않는다.

--app을 사용할 때의 기본 동작이다.

--no-pin-python

프로젝트에 .python-version 파일을 생성하지 않는다.

기본적으로 uv는 발견된 Python 인터프리터의 부 버전을 포함하는 .python-version 파일을 생성하며, 이로 인해 후속 uv 명령이 해당 버전을 사용하게 된다.

--no-progress

모든 진행률 출력을 숨긴다.

예: 스피너나 진행률 표시줄.

UV_NO_PROGRESS=1.2.3`)이 추가된다. 추가된 의존성을 반영하기 위해 lockfile과 프로젝트 환경이 업데이트된다. lockfile 업데이트를 건너뛰려면 `--frozen`을 사용한다. 환경 업데이트를 건너뛰려면 `--no-sync`를 사용한다. 요청한 의존성 중 하나라도 찾을 수 없으면 uv는 오류와 함께 종료된다. 단, `--frozen` 플래그가 제공된 경우 uv는 의존성이 존재하는지 또는 프로젝트와 호환되는지 확인하지 않고 그대로 추가한다. uv는 현재 디렉토리나 상위 디렉토리에서 프로젝트를 검색한다. 프로젝트를 찾을 수 없으면 uv는 오류와 함께 종료된다.

`사용법`



uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>


인자

PACKAGES
추가할 패키지, PEP 508 요구사항 형식 (예: ruff==0.5.0)



옵션

--active
프로젝트의 가상 환경보다 활성화된 가상 환경을 우선한다.

프로젝트 가상 환경이 활성화되었거나 가상 환경이 활성화되지 않은 경우 이 옵션은 효과가 없다.

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로 검증된 소스가 있는 보안 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--branch branch
Git에서 의존성을 추가할 때 사용할 브랜치

--cache-dir cache-dir
캐시 디렉토리의 경로.

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 터미널이나 TTY로 향할 때만 색상 출력을 활성화한다.

always:  감지된 환경에 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--compile-bytecode
설치 후 Python 파일을 바이트코드로 컴파일한다.

기본적으로 uv는 Python(.py) 파일을 바이트코드(__pycache__/*.pyc)로 컴파일하지 않는다. 대신 모듈이 처음 임포트될 때 지연 컴파일을 수행한다. CLI 애플리케이션이나 Docker 컨테이너와 같이 시작 시간이 중요한 경우, 이 옵션을 활성화하여 더 빠른 시작 시간을 위해 더 긴 설치 시간을 감수할 수 있다.

활성화된 경우, uv는 일관성을 위해 전체 site-packages 디렉토리(현재 작업에 의해 수정되지 않는 패키지 포함)를 처리한다. pip와 마찬가지로 오류도 무시한다.

UV_COMPILE_BYTECODE 환경 변수로도 설정할 수 있다.
--config-file config-file
구성에 사용할 uv.toml 파일의 경로.

uv 구성은 pyproject.toml 파일에 포함될 수 있지만, 이 컨텍스트에서는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정, KEY=VALUE 쌍으로 지정

--default-index default-index
기본 패키지 인덱스의 URL (기본값: <https://pypi.org/simple>).

PEP 503(단순 리포지토리 API)을 준수하는 리포지토리나 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 인덱스는 --index 플래그로 지정된 모든 인덱스보다 우선순위가 낮다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--dev
요구사항을 개발 의존성 그룹에 추가한다.

이 옵션은 --group dev의 별칭이다.

--directory directory
명령을 실행하기 전에 주어진 디렉토리로 변경한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--editable
요구사항을 편집 가능한 형태로 추가한다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z)와 시스템의 구성된 시간대에서 동일한 형식의 로컬 날짜(예: 2006-12-02)를 모두 받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra extra
의존성에 대해 활성화할 추가 기능.

여러 번 제공할 수 있다.

이 의존성을 선택적 추가 기능에 추가하려면 --optional을 참조한다.

--extra-index-url extra-index-url
(사용 중단: --index 대신 사용) --index-url에 추가로 사용할 패키지 인덱스의 추가 URL.

PEP 503(단순 리포지토리 API)을 준수하는 리포지토리나 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 모든 인덱스는 --index-url(기본값은 PyPI)로 지정된 인덱스보다 우선순위가 높다. 여러 --extra-index-url 플래그가 제공된 경우, 먼저 제공된 값이 우선순위가 높다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스에서 찾은 것 외에 후보 배포판을 검색할 위치.

경로인 경우, 대상은 최상위에 휠 파일(.whl)이나 소스 배포판(예: .tar.gz 또는 .zip)을 포함하는 디렉토리여야 한다.

URL인 경우, 페이지는 위에서 설명한 형식의 패키지 파일에 대한 링크의 평평한 목록을 포함해야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--fork-strategy fork-strategy
여러 Python 버전과 플랫폼에서 주어진 패키지의 여러 버전을 선택할 때 사용할 전략.

기본적으로 uv는 각 지원 Python 버전(requires-python)에 대해 각 패키지의 최신 버전을 선택하면서 플랫폼 간 선택된 버전 수를 최소화한다.

fewest 하에서는 uv는 각 패키지에 대해 선택된 버전 수를 최소화하며, 더 넓은 범위의 지원 Python 버전이나 플랫폼과 호환되는 이전 버전을 선호한다.

UV_FORK_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


fewest:  각 패키지에 대해 선택된 버전 수를 최소화한다. 더 넓은 범위의 지원 Python 버전이나 플랫폼과 호환되는 이전 버전을 선호한다.

requires-python:  각 지원 Python 버전에 대해 각 패키지의 최신 지원 버전을 선택한다.

--frozen
프로젝트를 다시 잠그지 않고 의존성을 추가한다.

프로젝트 환경은 동기화되지 않는다.

UV_FROZEN 환경 변수로도 설정할 수 있다.
--group group
지정된 의존성 그룹에 요구사항을 추가한다.

이 요구사항은 프로젝트의 게시된 메타데이터에 포함되지 않는다.

--help, -h
이 명령에 대한 간단한 도움말을 표시한다.

--index index
기본 인덱스 외에 의존성을 해결할 때 사용할 URL.

PEP 503(단순 리포지토리 API)을 준수하는 리포지토리나 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 모든 인덱스는 --default-index(기본값은 PyPI)로 지정된 인덱스보다 우선순위가 높다. 여러 --index 플래그가 제공된 경우, 먼저 제공된 값이 우선순위가 높다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략.

기본적으로 uv는 주어진 패키지가 사용 가능한 첫 번째 인덱스에서 멈추고, 해당 첫 번째 인덱스에 있는 결과로만 해결을 제한한다(first-index). 이는 공격자가 동일한 이름으로 악성 패키지를 대체 인덱스에 업로드할 수 있는 "의존성 혼란" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  주어진 패키지 이름에 대해 첫 번째로 일치하는 인덱스의 결과만 사용한다.

unsafe-first-match:  모든 인덱스에서 모든 패키지 이름을 검색하고, 첫 번째 인덱스의 버전을 모두 사용한 후 다음 인덱스로 이동한다.

unsafe-best-match:  모든 인덱스에서 모든 패키지 이름을 검색하고, "최고" 버전을 선호한다. 패키지 버전이 여러 인덱스에 있는 경우, 첫 번째 인덱스의 항목만 확인한다.

--index-url, -i index-url
(사용 중단: --default-index 대신 사용) Python 패키지 인덱스의 URL (기본값: <https://pypi.org/simple>).

PEP 503(단순 리포지토리 API)을 준수하는 리포지토리나 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 인덱스는 --extra-index-url 플래그로 지정된 모든 인덱스보다 우선순위가 낮다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--keyring-provider keyring-provider
인덱스 URL에 대한 인증을 위해 keyring을 사용하려고 시도한다.

현재는 --keyring-provider subprocess만 지원되며, 이는 uv가 인증을 처리하기 위해 keyring CLI를 사용하도록 구성한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회를 위해 keyring을 사용하지 않는다.

subprocess:  자격 증명 조회를 위해 keyring 명령을 사용한다.

--link-mode link-mode
글로벌 캐시에서 패키지를 설치할 때 사용할 방법.

기본값은 macOS에서 clone(Copy-on-Write라고도 함), Linux와 Windows에서 hardlink이다.

UV_LINK_MODE 환경 변수로도 설정할 수 있다.
가능한 값:


clone:  휠에서 site-packages 디렉토리로 패키지를 복제한다(즉, Copy-on-Write).

copy:  휠에서 site-packages 디렉토리로 패키지를 복사한다.

hardlink:  휠에서 site-packages 디렉토리로 패키지를 하드 링크한다.

symlink:  휠에서 site-packages 디렉토리로 패키지를 심볼릭 링크한다.

--locked
uv.lock이 변경되지 않을 것임을 확인한다.

lockfile이 최신 상태여야 한다. lockfile이 없거나 업데이트가 필요한 경우 uv는 오류와 함께 종료된다.

UV_LOCKED 환경 변수로도 설정할 수 있다.
--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 집합이며, uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 일부 경우, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-binary
미리 빌드된 휠을 설치하지 않는다.

주어진 패키지는 소스에서 빌드되어 설치된다. 리졸버는 여전히 패키지 메타데이터를 추출하기 위해 미리 빌드된 휠을 사용할 수 있다.

UV_NO_BINARY 환경 변수로도 설정할 수 있다.
--no-binary-package no-binary-package
특정 패키지에 대해 미리 빌드된 휠을 설치하지 않는다.

UV_NO_BINARY_PACKAGE 환경 변수로도 설정할 수 있다.
--no-build
소스 배포판을 빌드하지 않는다.

활성화된 경우, 리졸버는 임의의 Python 코드를 실행하지 않는다. 이미 빌드된 소스 배포판의 캐시된 휠이 재사용되지만, 배포판을 빌드해야 하는 작업은 오류와 함께 종료된다.

--no-build-isolation
소스 배포판을 빌드할 때 격리를 비활성화한다.

PEP 518에 의해 지정된 빌드 의존성이 이미 설치되어 있다고 가정한다.

UV_NO_BUILD_ISOLATION 환경 변수로도 설정할 수 있다.
--no-build-isolation-package no-build-isolation-package
특정 패키지에 대해 소스 배포판을 빌드할 때 격리를 비활성화한다.

패키지의 빌드 의존성이 PEP 518에 의해 이미 설치되어 있다고 가정한다.

--no-build-package no-build-package
특정 패키지에 대해 소스 배포판을 빌드하지 않는다.

--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
구성 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 구성 파일은 현재 디렉토리, 상위 디렉토리, 또는 사용자 구성 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-index
레지스트리 인덱스(예: PyPI)를 무시하고, 직접 URL 의존성과 --find-links로 제공된 의존성에만 의존한다.

--no-progress
모든 진행 상황 출력을 숨긴다.

예: 스피너나 진행률 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--no-sources
의존성을 해결할 때 tool.uv.sources 테이블을 무시한다. 워크스페이스, Git, URL, 또는 로컬 경로 소스를 사용하는 대신 표준을 준수하는 게시 가능한 패키지 메타데이터에 대해 잠그는 데 사용된다.

--no-sync
가상 환경 동기화를 건너뛴다.

UV_NO_SYNC 환경 변수로도 설정할 수 있다.
--offline
네트워크 액세스를 비활성화한다.

비활성화된 경우, uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--optional optional
요구사항을 지정된 추가 기능에 대한 패키지의 선택적 의존성에 추가한다.

그룹은 프로젝트를 설치할 때 --extra 플래그로 활성화할 수 있다.

이 요구사항에 대해 선택적 추가 기능을 활성화하려면 --extra를 참조한다.

--package package
워크스페이스의 특정 패키지에 의존성을 추가한다.

--prerelease prerelease
프리릴리스 버전을 고려할 때 사용할 전략.

기본적으로 uv는 프리릴리스만 출시하는 패키지와 선언된 지정자에 명시적 프리릴리스 마커가 포함된 자체 요구사항에 대해 프리릴리스를 허용한다(if-necessary-or-explicit).

UV_PRERELEASE 환경 변수로도 설정할 수 있다.
가능한 값:


disallow:  모든 프리릴리스 버전을 허용하지 않는다.

allow:  모든 프리릴리스 버전을 허용한다.

if-necessary:  패키지의 모든 버전이 프리릴리스인 경우 프리릴리스 버전을 허용한다.

explicit:  버전 요구사항에 명시적 프리릴리스 마커가 포함된 자체 패키지에 대해 프리릴리스 버전을 허용한다.

if-necessary-or-explicit:  패키지의 모든 버전이 프리릴리스이거나 패키지의 버전 요구사항에 명시적 프리릴리스 마커가 포함된 경우 프리릴리스 버전을 허용한다.

--project project
주어진 프로젝트 디렉토리 내에서 명령을 실행한다.

프로젝트 루트에서 디렉토리 트리를 올라가면서 모든 pyproject.toml, uv.toml, 및 .python-version 파일이 검색되며, 프로젝트의 가상 환경(.venv)도 검색된다.

다른 명령줄 인자(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python, -p python
해결 및 동기화에 사용할 Python 인터프리터.

Python 검색 및 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참조한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 여부.

기본적으로 uv는 관리하는 Python 버전을 선호한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션은 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리하는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리하는 Python 설치를 선호한다.

system:  관리하는 Python 설치보다 시스템 Python 설치를 선호한다.

only-system:  시스템 Python 설치만 사용한다. 관리하는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--raw-sources
소스 요구사항을 tool.uv.sources가 아닌 project.dependencies에 추가한다.

기본적으로 uv는 Git, 로컬, 편집 가능, 및 직접 URL 요구사항에 대한 소스 정보를 기록하기 위해 tool.uv.sources 섹션을 사용한다.

--refresh
모든 캐시 데이터를 새로 고친다.

--refresh-package refresh-package
특정 패키지에 대한 캐시 데이터를 새로 고친다.

--reinstall
이미 설치된 패키지와 관계없이 모든 패키지를 다시 설치한다. --refresh를 암시한다.

--reinstall-package reinstall-package
이미 설치된 패키지와 관계없이 특정 패키지를 다시 설치한다. --refresh-package를 암시한다.

--requirements, -r requirements
주어진 requirements.txt 파일에 나열된 모든 패키지를 추가한다.

--resolution resolution
주어진 패키지 요구사항에 대해 서로 다른 호환 버전을 선택할 때 사용할 전략.

기본적으로 uv는 각 패키지의 최신 호환 버전을 사용한다(highest).

UV_RESOLUTION 환경 변수로도 설정할 수 있다.
가능한 값:


highest:  각 패키지의 최고 호환 버전을 해결한다.

lowest:  각 패키지의 최저 호환 버전을 해결한다.

lowest-direct:  모든 직접 의존성의 최저 호환 버전을 해결하고, 모든 전이 의존성의 최고 호환 버전을 해결한다.

--rev rev
Git에서 의존성을 추가할 때 사용할 커밋

--script script
프로젝트가 아닌 지정된 Python 스크립트에 의존성을 추가한다.

제공된 경우, uv는 스크립트의 인라인 메타데이터 테이블에 의존성을 추가하며, PEP 723을 준수한다. 해당 인라인 메타데이터 테이블이 없는 경우, 새로 생성되어 스크립트에 추가된다. uv run으로 실행할 때, uv는 모든 인라인 의존성이 설치된 스크립트에 대한 임시 환경을 생성한다.

--tag tag
Git에서 의존성을 추가할 때 사용할 태그

--upgrade, -U
기존 출력 파일에 고정된 버전을 무시하고 패키지 업그레이드를 허용한다. --refresh를 암시한다.

--upgrade-package, -P upgrade-package
기존 출력 파일에 고정된 버전을 무시하고 특정 패키지의 업그레이드를 허용한다. --refresh-package를 암시한다.

--verbose, -v
자세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용하여 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




## uv remove

프로젝트에서 의존성을 제거한다.

의존성은 프로젝트의 `pyproject.toml` 파일에서 제거된다.

특정 의존성에 대해 여러 항목이 존재하는 경우(예: 각각 다른 마커를 가진 경우), 모든 항목이 제거된다.

락 파일과 프로젝트 환경은 제거된 의존성을 반영하도록 업데이트된다. 락 파일 업데이트를 건너뛰려면 `--frozen`을 사용한다. 환경 업데이트를 건너뛰려면 `--no-sync`를 사용한다.

요청한 의존성이 프로젝트에 존재하지 않으면 uv는 오류와 함께 종료된다.

`uv pip install`로 수동으로 설치한 패키지는 `uv remove`로 제거되지 않는다.

uv는 현재 디렉토리나 상위 디렉토리에서 프로젝트를 검색한다. 프로젝트를 찾을 수 없으면 uv는 오류와 함께 종료된다.

사용법

uv remove [OPTIONS] <PACKAGES>...


인수

PACKAGES
제거할 의존성 이름 (예: ruff)



옵션

--active
프로젝트의 가상 환경보다 활성화된 가상 환경을 우선한다.

프로젝트 가상 환경이 활성화되었거나 활성화된 가상 환경이 없으면 이 옵션은 효과가 없다.

--allow-insecure-host allow-insecure-host
호스트에 대한 안전하지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소와 비교해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 안전한 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리 경로.

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전달될 때만 색상 출력을 활성화한다.

always:  환경과 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--compile-bytecode
설치 후 Python 파일을 바이트코드로 컴파일한다.

기본적으로 uv는 Python(.py) 파일을 바이트코드(__pycache__/*.pyc)로 컴파일하지 않는다. 대신 모듈을 처음 임포트할 때 지연 컴파일을 수행한다. CLI 애플리케이션이나 Docker 컨테이너와 같이 시작 시간이 중요한 경우, 이 옵션을 활성화해 더 긴 설치 시간과 빠른 시작 시간을 교환할 수 있다.

활성화하면 uv는 일관성을 위해 전체 site-packages 디렉토리(현재 작업으로 수정되지 않은 패키지 포함)를 처리한다. pip와 마찬가지로 오류도 무시한다.

UV_COMPILE_BYTECODE 환경 변수로도 설정할 수 있다.
--config-file config-file
설정에 사용할 uv.toml 파일 경로.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정을 KEY=VALUE 쌍으로 지정한다.

--default-index default-index
기본 패키지 인덱스 URL (기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 지정된 인덱스는 --index 플래그로 지정된 다른 모든 인덱스보다 낮은 우선순위를 가진다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--dev
개발 의존성 그룹에서 패키지를 제거한다.

이 옵션은 --group dev의 별칭이다.

--directory directory
명령 실행 전 주어진 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참고한다.

--exclude-newer exclude-newer
후보 패키지를 주어진 날짜 이전에 업로드된 것으로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z)와 시스템의 시간대 설정에 따른 동일 형식의 로컬 날짜(예: 2006-12-02)를 입력받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra-index-url extra-index-url
(사용 중단: --index 대신 사용) --index-url에 추가로 사용할 패키지 인덱스 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 제공된 모든 인덱스는 --index-url로 지정된 인덱스(기본값: PyPI)보다 높은 우선순위를 가진다. 여러 --extra-index-url 플래그가 제공되면 먼저 제공된 값이 우선순위를 가진다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스에서 찾은 것 외에 후보 배포판을 검색할 위치.

경로인 경우, 대상은 최상위에 패키지가 휠 파일(.whl) 또는 소스 배포판(예: .tar.gz 또는 .zip)으로 포함된 디렉토리여야 한다.

URL인 경우, 페이지는 위에서 설명한 형식을 준수하는 패키지 파일에 대한 링크의 단순 목록을 포함해야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--fork-strategy fork-strategy
여러 Python 버전과 플랫폼 간에 주어진 패키지의 여러 버전을 선택할 때 사용할 전략.

기본적으로 uv는 지원되는 Python 버전(requires-python)마다 각 패키지의 최신 버전을 선택하고, 플랫폼 간 선택된 버전 수를 최소화한다.

fewest를 선택하면 uv는 각 패키지의 선택된 버전 수를 최소화하며, 지원되는 Python 버전이나 플랫폼 범위가 더 넓은 이전 버전을 선호한다.

UV_FORK_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


fewest:  각 패키지의 선택된 버전 수를 최소화하도록 최적화한다. 지원되는 Python 버전이나 플랫폼 범위가 더 넓은 이전 버전을 선호할 수 있다.

requires-python:  지원되는 Python 버전마다 각 패키지의 최신 지원 버전을 선택하도록 최적화한다.

--frozen
의존성을 제거하되 프로젝트를 다시 락하지 않는다.

프로젝트 환경은 동기화되지 않는다.

UV_FROZEN 환경 변수로도 설정할 수 있다.
--group group
지정된 의존성 그룹에서 패키지를 제거한다.

--help, -h
이 명령에 대한 간단한 도움말을 표시한다.

--index index
의존성 해결에 사용할 URL을 기본 인덱스에 추가한다.

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 제공된 모든 인덱스는 --default-index로 지정된 인덱스(기본값: PyPI)보다 높은 우선순위를 가진다. 여러 --index 플래그가 제공되면 먼저 제공된 값이 우선순위를 가진다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략.

기본적으로 uv는 주어진 패키지가 사용 가능한 첫 번째 인덱스에서 멈추고, 첫 번째 인덱스에 있는 것으로 해결을 제한한다(first-index). 이는 공격자가 동일한 이름으로 악성 패키지를 대체 인덱스에 업로드할 수 있는 "의존성 혼란" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  주어진 패키지 이름에 대해 첫 번째로 일치하는 인덱스의 결과만 사용한다.

unsafe-first-match:  모든 인덱스에서 각 패키지 이름을 검색하며, 첫 번째 인덱스의 버전을 모두 소진한 후 다음 인덱스로 이동한다.

unsafe-best-match:  모든 인덱스에서 각 패키지 이름을 검색하며, "최고" 버전을 선호한다. 패키지 버전이 여러 인덱스에 있는 경우 첫 번째 인덱스의 항목만 확인한다.

--index-url, -i index-url
(사용 중단: --default-index 대신 사용) Python 패키지 인덱스 URL (기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 지정된 인덱스는 --extra-index-url 플래그로 지정된 다른 모든 인덱스보다 낮은 우선순위를 가진다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--keyring-provider keyring-provider
인덱스 URL에 대한 인증에 keyring 사용을 시도한다.

현재는 --keyring-provider subprocess만 지원되며, uv가 keyring CLI를 사용해 인증을 처리하도록 설정한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회에 keyring을 사용하지 않는다.

subprocess:  keyring 커맨드를 사용해 자격 증명을 조회한다.

--link-mode link-mode
전역 캐시에서 패키지를 설치할 때 사용할 방법.

기본값은 macOS에서 clone(Copy-on-Write라고도 함), Linux와 Windows에서 hardlink이다.

UV_LINK_MODE 환경 변수로도 설정할 수 있다.
가능한 값:


clone:  휠에서 site-packages 디렉토리로 패키지를 복제한다(즉, Copy-on-Write).

copy:  휠에서 site-packages 디렉토리로 패키지를 복사한다.

hardlink:  휠에서 site-packages 디렉토리로 패키지를 하드 링크한다.

symlink:  휠에서 site-packages 디렉토리로 패키지를 심볼릭 링크한다.

--locked
uv.lock이 변경되지 않을 것임을 확인한다.

락 파일이 최신 상태여야 한다. 락 파일이 없거나 업데이트가 필요하면 uv는 오류와 함께 종료된다.

UV_LOCKED 환경 변수로도 설정할 수 있다.
--native-tls
플랫폼의 네이티브 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용해야 하는 경우, 플랫폼의 네이티브 인증서 저장소를 사용하고 싶을 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-binary
미리 빌드된 휠을 설치하지 않는다.

주어진 패키지는 소스에서 빌드되어 설치된다. 리졸버는 여전히 패키지 메타데이터를 추출하기 위해 미리 빌드된 휠을 사용할 수 있다.

UV_NO_BINARY 환경 변수로도 설정할 수 있다.
--no-binary-package no-binary-package
특정 패키지에 대해 미리 빌드된 휠을 설치하지 않는다.

UV_NO_BINARY_PACKAGE 환경 변수로도 설정할 수 있다.
--no-build
소스 배포판을 빌드하지 않는다.

활성화하면 임의의 Python 코드를 실행하지 않는다. 이미 빌드된 소스 배포판의 캐시된 휠은 재사용되지만, 배포판을 빌드해야 하는 작업은 오류와 함께 종료된다.

--no-build-isolation
소스 배포판을 빌드할 때 격리를 비활성화한다.

PEP 518로 지정된 빌드 의존성이 이미 설치되어 있다고 가정한다.

UV_NO_BUILD_ISOLATION 환경 변수로도 설정할 수 있다.
--no-build-isolation-package no-build-isolation-package
특정 패키지에 대해 소스 배포판을 빌드할 때 격리를 비활성화한다.

패키지의 빌드 의존성이 PEP 518로 지정되어 이미 설치되어 있다고 가정한다.

--no-build-package no-build-package
특정 패키지에 대해 소스 배포판을 빌드하지 않는다.

--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리, 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-index
레지스트리 인덱스(예: PyPI)를 무시하고, 직접 URL 의존성과 --find-links로 제공된 것에 의존한다.

--no-progress
모든 진행 상황 출력을 숨긴다.

예: 스피너 또는 진행률 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python 자동 다운로드를 비활성화한다.

--no-sources
tool.uv.sources 테이블을 무시하고 의존성을 해결한다. 워크스페이스, Git, URL, 또는 로컬 경로 소스 대신 표준을 준수하고 게시 가능한 패키지 메타데이터에 대해 락하도록 사용된다.

--no-sync
프로젝트를 다시 락한 후 가상 환경을 동기화하지 않는다.

UV_NO_SYNC 환경 변수로도 설정할 수 있다.
--offline
네트워크 액세스를 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--optional optional
지정된 extra에 대한 프로젝트의 선택적 의존성에서 패키지를 제거한다.

--package package
워크스페이스의 특정 패키지에서 의존성을 제거한다.

--prerelease prerelease
프리릴리스 버전을 고려할 때 사용할 전략.

기본적으로 uv는 오직 프리릴리스를 출시하는 패키지와 선언된 지정자에 명시적 프리릴리스 마커가 포함된 1자 의존성에 대해 프리릴리스를 허용한다(if-necessary-or-explicit).

UV_PRERELEASE 환경 변수로도 설정할 수 있다.
가능한 값:


disallow:  모든 프리릴리스 버전을 허용하지 않는다.

allow:  모든 프리릴리스 버전을 허용한다.

if-necessary:  패키지의 모든 버전이 프리릴리스인 경우 프리릴리스 버전을 허용한다.

explicit:  1자 패키지가 버전 요구 사항에 명시적 프리릴리스 마커가 있는 경우 프리릴리스 버전을 허용한다.

if-necessary-or-explicit:  패키지의 모든 버전이 프리릴리스이거나 패키지가 버전 요구 사항에 명시적 프리릴리스 마커가 있는 경우 프리릴리스 버전을 허용한다.

--project project
주어진 프로젝트 디렉토리 내에서 명령을 실행한다.

모든 pyproject.toml, uv.toml, 및 .python-version 파일은 프로젝트 루트에서 디렉토리 트리를 따라 올라가며 검색되며, 프로젝트의 가상 환경(.venv)도 마찬가지이다.

기타 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참고한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python, -p python
해결 및 동기화에 사용할 Python 인터프리터.

Python 검색 및 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참고한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 여부.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system:  시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--refresh
모든 캐시 데이터를 새로 고친다.

--refresh-package refresh-package
특정 패키지에 대한 캐시 데이터를 새로 고친다.

--reinstall
이미 설치되었는지 여부와 관계없이 모든 패키지를 다시 설치한다. --refresh를 암시한다.

--reinstall-package reinstall-package
이미 설치되었는지 여부와 관계없이 특정 패키지를 다시 설치한다. --refresh-package를 암시한다.

--resolution resolution
주어진 패키지 요구 사항에 대해 서로 다른 호환 버전을 선택할 때 사용할 전략.

기본적으로 uv는 각 패키지의 최신 호환 버전을 사용한다(highest).

UV_RESOLUTION 환경 변수로도 설정할 수 있다.
가능한 값:


highest:  각 패키지의 최신 호환 버전을 해결한다.

lowest:  각 패키지의 최저 호환 버전을 해결한다.

lowest-direct:  직접 의존성의 최저 호환 버전을 해결하고, 전이 의존성의 최신 호환 버전을 해결한다.

--script script
프로젝트가 아닌 지정된 Python 스크립트에서 의존성을 제거한다.

제공되면 uv는 PEP 723에 따라 스크립트의 인라인 메타데이터 테이블에서 의존성을 제거한다.

--upgrade, -U
패키지 업그레이드를 허용하고, 기존 출력 파일에 고정된 버전을 무시한다. --refresh를 암시한다.

--upgrade-package, -P upgrade-package
특정 패키지에 대해 업그레이드를 허용하고, 기존 출력 파일에 고정된 버전을 무시한다. --refresh-package를 암시한다.

--verbose, -v
상세 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




## uv sync

프로젝트 환경을 업데이트한다.

sync를 실행하면 프로젝트의 모든 의존성이 설치되고, lockfile과 동기화된다.

기본적으로 정확한 동기화를 수행한다: uv는 프로젝트 의존성으로 선언되지 않은 패키지를 제거한다. 불필요한 패키지를 유지하려면 `--inexact` 플래그를 사용한다. 단, 불필요한 패키지가 프로젝트 의존성과 충돌하면 여전히 제거된다. 또한 `--no-build-isolation`을 사용하면 uv는 빌드 의존성을 제거하지 않기 위해 불필요한 패키지를 제거하지 않는다.

프로젝트 가상 환경(`.venv`)이 존재하지 않으면 생성된다.

`--locked` 또는 `--frozen` 플래그를 제공하지 않으면, sync 전에 프로젝트를 다시 잠근다.

uv는 현재 디렉토리나 상위 디렉토리에서 프로젝트를 검색한다. 프로젝트를 찾을 수 없으면 uv는 오류와 함께 종료된다.

lockfile에서 설치할 때, uv는 yanked된 패키지 버전에 대해 경고를 제공하지 않는다.

사용법

uv sync [OPTIONS]


옵션

--active
활성 가상 환경에 의존성을 동기화한다.

프로젝트나 스크립트를 위한 가상 환경을 생성하거나 업데이트하는 대신, `VIRTUAL_ENV` 환경 변수가 설정된 경우 활성 가상 환경을 우선 사용한다.

--all-extras
모든 선택적 의존성을 포함한다.

`tool.uv.conflicts`에서 두 개 이상의 extras가 충돌로 선언된 경우, 이 플래그를 사용하면 항상 오류가 발생한다.

모든 선택적 의존성은 항상 해결에 포함된다. 이 옵션은 설치할 패키지 선택에만 영향을 미친다.

--all-groups
모든 의존성 그룹에서 의존성을 포함한다.

--no-group을 사용하여 특정 그룹을 제외할 수 있다.

--all-packages
작업 공간의 모든 패키지를 동기화한다.

작업 공간의 환경(`.venv`)이 모든 작업 공간 멤버를 포함하도록 업데이트된다.

--extra, --group 또는 관련 옵션을 통해 지정된 extras나 그룹은 모든 작업 공간 멤버에 적용된다.

--allow-insecure-host allow-insecure-host
호스트에 대한 보안되지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 보안 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에 색상을 사용할지 여부를 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 향할 때만 색상 출력을 활성화한다.

always:  감지된 환경과 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--compile-bytecode
설치 후 Python 파일을 바이트코드로 컴파일한다.

기본적으로 uv는 Python(.py) 파일을 바이트코드(__pycache__/*.pyc)로 컴파일하지 않는다. 대신, 모듈을 처음 임포트할 때 지연 컴파일을 수행한다. CLI 애플리케이션이나 Docker 컨테이너와 같이 시작 시간이 중요한 경우, 이 옵션을 활성화하여 설치 시간을 늘리는 대신 시작 시간을 단축할 수 있다.

활성화하면, uv는 일관성을 위해 전체 site-packages 디렉토리(현재 작업으로 수정되지 않은 패키지 포함)를 처리한다. pip처럼 오류도 무시한다.

UV_COMPILE_BYTECODE 환경 변수로도 설정할 수 있다.
--config-file config-file
구성을 위해 사용할 uv.toml 파일 경로.

uv 구성은 pyproject.toml 파일에 포함될 수 있지만, 이 컨텍스트에서는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정을 KEY=VALUE 쌍으로 지정한다.

--default-index default-index
기본 패키지 인덱스 URL(기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소나 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 지정된 인덱스는 --index 플래그로 지정된 모든 다른 인덱스보다 낮은 우선순위를 가진다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 주어진 디렉토리로 변경한다.

상대 경로는 주어진 디렉토리를 기준으로 해결된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--dry-run
실제로 lockfile을 쓰거나 프로젝트 환경을 수정하지 않고 시뮬레이션을 실행한다.

시뮬레이션 모드에서 uv는 프로젝트의 의존성을 해결하고 lockfile과 프로젝트 환경에 대한 변경 사항을 보고하지만, 실제로 수정하지는 않는다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지로 후보를 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z)나 시스템의 구성된 시간대에서 동일한 형식의 로컬 날짜(예: 2006-12-02)를 받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra extra
지정된 extra 이름에서 선택적 의존성을 포함한다.

여러 번 제공할 수 있다.

tool.uv.conflicts에 나타나는 여러 extras나 그룹을 지정하면 uv는 오류를 보고한다.

모든 선택적 의존성은 항상 해결에 포함된다. 이 옵션은 설치할 패키지 선택에만 영향을 미친다.

--extra-index-url extra-index-url
(사용 중단: --index 대신 사용) --index-url 외에 사용할 추가 패키지 인덱스 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소나 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 모든 인덱스는 --index-url로 지정된 인덱스(기본값: PyPI)보다 높은 우선순위를 가진다. 여러 --extra-index-url 플래그를 제공하면, 이전 값이 우선순위를 가진다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스에서 찾은 것 외에 후보 배포를 검색할 위치.

경로인 경우, 대상은 최상위 수준에서 wheel 파일(.whl)이나 소스 배포(예: .tar.gz 또는 .zip)를 포함하는 디렉토리여야 한다.

URL인 경우, 페이지는 위에서 설명한 형식의 패키지 파일에 대한 링크의 평면 목록을 포함해야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--fork-strategy fork-strategy
여러 Python 버전과 플랫폼에서 주어진 패키지의 여러 버전을 선택할 때 사용할 전략.

기본적으로 uv는 각 지원 Python 버전(requires-python)에 대해 각 패키지의 최신 버전을 선택하고, 플랫폼 간 선택된 버전 수를 최소화한다.

fewest에서는 uv는 각 패키지에 대해 선택된 버전 수를 최소화하고, 지원 Python 버전이나 플랫폼의 더 넓은 범위와 호환되는 이전 버전을 선호한다.

UV_FORK_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


fewest:  각 패키지에 대해 선택된 버전 수를 최소화한다. 지원 Python 버전이나 플랫폼의 더 넓은 범위와 호환되는 이전 버전을 선호한다.

requires-python:  각 지원 Python 버전에 대해 각 패키지의 최신 지원 버전을 선택한다.

--frozen
uv.lock 파일을 업데이트하지 않고 동기화한다.

lockfile이 최신인지 확인하는 대신, lockfile의 버전을 진리 소스로 사용한다. lockfile이 없으면 uv는 오류와 함께 종료된다. pyproject.toml에 lockfile에 아직 포함되지 않은 의존성 변경 사항이 포함되어 있으면 환경에 존재하지 않는다.

UV_FROZEN 환경 변수로도 설정할 수 있다.
--group group
지정된 의존성 그룹에서 의존성을 포함한다.

tool.uv.conflicts에 나타나는 여러 extras나 그룹을 지정하면 uv는 오류를 보고한다.

여러 번 제공할 수 있다.

--help, -h
이 명령에 대한 간결한 도움말을 표시한다.

--index index
기본 인덱스 외에 의존성을 해결할 때 사용할 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소나 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 모든 인덱스는 --default-index로 지정된 인덱스(기본값: PyPI)보다 높은 우선순위를 가진다. 여러 --index 플래그를 제공하면, 이전 값이 우선순위를 가진다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략.

기본적으로 uv는 주어진 패키지가 사용 가능한 첫 번째 인덱스에서 멈추고, 첫 번째 인덱스에 있는 해결로 제한한다(first-index). 이는 공격자가 동일한 이름으로 악성 패키지를 대체 인덱스에 업로드할 수 있는 "의존성 혼동" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  주어진 패키지 이름에 대해 첫 번째 일치하는 인덱스의 결과만 사용한다.

unsafe-first-match:  모든 인덱스에서 모든 패키지 이름을 검색하고, 첫 번째 인덱스의 버전을 모두 소진한 후 다음 인덱스로 이동한다.

unsafe-best-match:  모든 인덱스에서 모든 패키지 이름을 검색하고, "최고" 버전을 선호한다. 패키지 버전이 여러 인덱스에 있는 경우, 첫 번째 인덱스의 항목만 본다.

--index-url, -i index-url
(사용 중단: --default-index 대신 사용) Python 패키지 인덱스 URL(기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소나 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 지정된 인덱스는 --extra-index-url 플래그로 지정된 모든 다른 인덱스보다 낮은 우선순위를 가진다.

UV_INDEX_URL 환경 변수로도 설정할


## uv lock

프로젝트의 lockfile을 업데이트한다.

프로젝트 lockfile(`uv.lock`)이 존재하지 않으면 새로 생성한다. lockfile이 이미 존재하면 그 내용을 해결(resolution)에 대한 기본 설정으로 사용한다.

프로젝트의 의존성에 변경 사항이 없으면 `--upgrade` 플래그를 제공하지 않는 한 lock 작업은 아무런 영향을 미치지 않는다.

사용법

uv lock [OPTIONS]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 소스가 있는 보안된 네트워크에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로를 지정한다.

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--check
lockfile이 최신 상태인지 확인한다.

uv.lock이 해결 후에도 변경되지 않을 것임을 단언한다. lockfile이 없거나 업데이트가 필요한 경우 uv는 오류와 함께 종료된다.

--locked와 동일하다.

UV_LOCKED 환경 변수로도 설정할 수 있다.
--check-exists
uv.lock이 존재하는지 확인하되, 최신 상태인지는 확인하지 않는다.

--frozen와 동일하다.

UV_FROZEN 환경 변수로도 설정할 수 있다.
--color color-choice
출력에 색상을 사용할지 여부를 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 터미널이나 TTY로 향할 때만 색상 출력을 활성화한다.

always:  환경과 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정에 사용할 uv.toml 파일의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정을 KEY=VALUE 쌍으로 지정한다.

--default-index default-index
기본 패키지 인덱스의 URL을 지정한다(기본값: <https://pypi.org/simple>).

PEP 503을 준수하는 리포지토리(단순 리포지토리 API) 또는 동일한 형식으로 구성된 로컬 디렉토리를 입력받는다.

이 플래그로 지정된 인덱스는 --index 플래그로 지정된 모든 인덱스보다 우선순위가 낮다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 지정된 디렉토리로 이동한다.

상대 경로는 지정된 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--dry-run
dry-run 모드로 실행하여 lockfile을 실제로 작성하지 않는다.

dry-run 모드에서 uv는 프로젝트의 의존성을 해결하고 결과적인 변경 사항을 보고하지만, lockfile을 디스크에 기록하지는 않는다.

--exclude-newer exclude-newer
후보 패키지를 지정된 날짜 이전에 업로드된 것으로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z)와 시스템의 시간대에 따른 로컬 날짜(예: 2006-12-02)를 모두 입력받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra-index-url extra-index-url
(더 이상 사용되지 않음: --index를 대신 사용) --index-url에 추가로 사용할 패키지 인덱스의 URL을 지정한다.

PEP 503을 준수하는 리포지토리(단순 리포지토리 API) 또는 동일한 형식으로 구성된 로컬 디렉토리를 입력받는다.

이 플래그로 제공된 모든 인덱스는 --index-url로 지정된 인덱스(기본적으로 PyPI)보다 우선순위가 높다. 여러 --extra-index-url 플래그가 제공되면 먼저 제공된 값이 우선순위를 가진다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스에서 찾은 것 외에 후보 배포판을 검색할 위치를 지정한다.

경로인 경우, 대상은 최상위 레벨에 휠 파일(.whl) 또는 소스 배포판(예: .tar.gz 또는 .zip)이 포함된 디렉토리여야 한다.

URL인 경우, 페이지는 위에서 설명한 형식을 준수하는 패키지 파일에 대한 링크의 평면 목록을 포함해야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--fork-strategy fork-strategy
여러 Python 버전과 플랫폼에 걸쳐 특정 패키지의 여러 버전을 선택할 때 사용할 전략을 지정한다.

기본적으로 uv는 각 지원되는 Python 버전(requires-python)에 대해 각 패키지의 최신 버전을 선택하도록 최적화하며, 동시에 플랫폼 간 선택된 버전 수를 최소화한다.

fewest를 선택하면 uv는 각 패키지에 대해 선택된 버전 수를 최소화하며, 더 넓은 범위의 지원 Python 버전 또는 플랫폼과 호환되는 이전 버전을 선호한다.

UV_FORK_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


fewest:  각 패키지에 대해 선택된 버전 수를 최소화하도록 최적화한다. 더 넓은 범위의 지원 Python 버전 또는 플랫폼과 호환되는 이전 버전을 선호한다.

requires-python:  각 지원 Python 버전에 대해 지원되는 최신 버전의 패키지를 선택하도록 최적화한다.

--help, -h
이 명령에 대한 간결한 도움말을 표시한다.

--index index
의존성을 해결할 때 사용할 URL을 지정한다. 기본 인덱스에 추가된다.

PEP 503을 준수하는 리포지토리(단순 리포지토리 API) 또는 동일한 형식으로 구성된 로컬 디렉토리를 입력받는다.

이 플래그로 제공된 모든 인덱스는 --default-index로 지정된 인덱스(기본적으로 PyPI)보다 우선순위가 높다. 여러 --index 플래그가 제공되면 먼저 제공된 값이 우선순위를 가진다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략을 지정한다.

기본적으로 uv는 특정 패키지가 사용 가능한 첫 번째 인덱스에서 멈추고, 해당 첫 번째 인덱스에 있는 해결만을 제한한다(first-index). 이는 공격자가 대체 인덱스에 동일한 이름으로 악성 패키지를 업로드할 수 있는 "의존성 혼동" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  특정 패키지 이름에 대해 첫 번째로 일치하는 인덱스의 결과만 사용한다.

unsafe-first-match:  모든 인덱스에서 각 패키지 이름을 검색하며, 첫 번째 인덱스의 버전을 모두 소진한 후 다음 인덱스로 이동한다.

unsafe-best-match:  모든 인덱스에서 각 패키지 이름을 검색하며, "가장 좋은" 버전을 선호한다. 패키지 버전이 여러 인덱스에 있는 경우 첫 번째 인덱스의 항목만 살펴본다.

--index-url, -i index-url
(더 이상 사용되지 않음: --default-index를 대신 사용) Python 패키지 인덱스의 URL을 지정한다(기본값: <https://pypi.org/simple>).

PEP 503을 준수하는 리포지토리(단순 리포지토리 API) 또는 동일한 형식으로 구성된 로컬 디렉토리를 입력받는다.

이 플래그로 지정된 인덱스는 --extra-index-url 플래그로 지정된 모든 인덱스보다 우선순위가 낮다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--keyring-provider keyring-provider
인덱스 URL에 대한 인증을 위해 keyring을 사용하려고 시도한다.

현재는 --keyring-provider subprocess만 지원되며, 이는 uv가 keyring CLI를 사용하여 인증을 처리하도록 설정한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회에 keyring을 사용하지 않는다.

subprocess:  keyring 명령을 사용하여 자격 증명을 조회한다.

--link-mode link-mode
글로벌 캐시에서 패키지를 설치할 때 사용할 방법을 지정한다.

이 옵션은 소스 배포판을 빌드할 때만 사용된다.

기본값은 macOS에서 clone(Copy-on-Write), Linux와 Windows에서는 hardlink이다.

UV_LINK_MODE 환경 변수로도 설정할 수 있다.
가능한 값:


clone:  휠에서 site-packages 디렉토리로 패키지를 복제한다(즉, Copy-on-Write).

copy:  휠에서 site-packages 디렉토리로 패키지를 복사한다.

hardlink:  휠에서 site-packages 디렉토리로 패키지를 하드 링크한다.

symlink:  휠에서 site-packages 디렉토리로 패키지를 심볼릭 링크한다.

--native-tls
플랫폼의 네이티브 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, 이를 uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 일부 경우에는, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우, 플랫폼의 네이티브 인증서 저장소를 사용하고 싶을 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-binary
미리 빌드된 휠을 설치하지 않는다.

지정된 패키지는 소스에서 빌드되어 설치된다. 해결자는 여전히 패키지 메타데이터를 추출하기 위해 미리 빌드된 휠을 사용할 수 있다.

UV_NO_BINARY 환경 변수로도 설정할 수 있다.
--no-binary-package no-binary-package
특정 패키지에 대해 미리 빌드된 휠을 설치하지 않는다.

UV_NO_BINARY_PACKAGE 환경 변수로도 설정할 수 있다.
--no-build
소스 배포판을 빌드하지 않는다.

활성화되면 해결은 임의의 Python 코드를 실행하지 않는다. 이미 빌드된 소스 배포판의 캐시된 휠이 재사용되지만, 배포판을 빌드해야 하는 작업은 오류와 함께 종료된다.

--no-build-isolation
소스 배포판을 빌드할 때 격리를 비활성화한다.

PEP 518에 의해 지정된 빌드 의존성이 이미 설치되어 있다고 가정한다.

UV_NO_BUILD_ISOLATION 환경 변수로도 설정할 수 있다.
--no-build-isolation-package no-build-isolation-package
특정 패키지에 대해 소스 배포판을 빌드할 때 격리를 비활성화한다.

패키지의 빌드 의존성이 PEP 518에 의해 이미 설치되어 있다고 가정한다.

--no-build-package no-build-package
특정 패키지에 대해 소스 배포판을 빌드하지 않는다.

--no-cache, -n
작업 기간 동안 캐시에서 읽거나 쓰지 않고 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리, 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-index
레지스트리 인덱스(예: PyPI)를 무시하고, 직접 URL 의존성과 --find-links로 제공된 것만 사용한다.

--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄이 포함된다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--no-sources
의존성을 해결할 때 tool.uv.sources 테이블을 무시한다. 워크스페이스, Git, URL, 또는 로컬 경로 소스를 사용하는 대신 표준을 준수하고 게시 가능한 패키지 메타데이터에 대해 잠그는 데 사용된다.

--offline
네트워크 접근을 비활성화한다.

비활성화되면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--prerelease prerelease
프리릴리스 버전을 고려할 때 사용할 전략을 지정한다.

기본적으로 uv는 프리릴리스만 출시하는 패키지와 선언된 지정자에 명시적 프리릴리스 마커가 포함된 첫 번째 파티 요구 사항에 대해 프리릴리스를 허용한다(if-necessary-or-explicit).

UV_PRERELEASE 환경 변수로도 설정할 수 있다.
가능한 값:


disallow:  모든 프리릴리스 버전을 허용하지 않는다.

allow:  모든 프리릴리스 버전을 허용한다.

if-necessary:  패키지의 모든 버전이 프리릴리스인 경우 프리릴리스 버전을 허용한다.

explicit:  첫 번째 파티 패키지의 버전 요구 사항에 명시적 프리릴리스 마커가 있는 경우 프리릴리스 버전을 허용한다.

if-necessary-or-explicit:  패키지의 모든 버전이 프리릴리스이거나 패키지의 버전 요구 사항에 명시적 프리릴리스 마커가 있는 경우 프리릴리스 버전을 허용한다.

--project project
지정된 프로젝트 디렉토리 내에서 명령을 실행한다.

프로젝트 루트에서 디렉토리 트리를 올라가며 pyproject.toml, uv.toml, .python-version 파일을 검색하고, 프로젝트의 가상 환경(.venv)도 검색한다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때는 효과가 없다.

--python, -p python
해결 과정에서 사용할 Python 인터프리터를 지정한다.

Python 인터프리터는 휠이 없는 경우 패키지 메타데이터를 결정하기 위해 소스 배포판을 빌드할 때 필요하다.

인터프리터는 또한 requires-python이 설정되지 않은 경우 최소 Python 버전에 대한 대체 값으로 사용된다.

Python 검색 및 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참조한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 선호할지 지정한다.

기본적으로 uv는 관리하는 Python 버전을 사용하는 것을 선호한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리하는 Python 설치만 사용한다; 시스템 Python 설치를 절대 사용하지 않는다.

managed:  시스템 Python 설치보다 관리하는 Python 설치를 선호한다.

system:  관리하는 Python 설치보다 시스템 Python 설치를 선호한다.

only-system:  시스템 Python 설치만 사용한다; 관리하는 Python 설치를 절대 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--refresh
모든 캐시 데이터를 새로 고친다.

--refresh-package refresh-package
특정 패키지의 캐시 데이터를 새로 고친다.

--resolution resolution
특정 패키지 요구 사항에 대해 여러 호환 가능한 버전 중 선택할 때 사용할 전략을 지정한다.

기본적으로 uv는 각 패키지의 최신 호환 버전을 사용한다(highest).

UV_RESOLUTION 환경 변수로도 설정할 수 있다.
가능한 값:


highest:  각 패키지의 최신 호환 버전을 해결한다.

lowest:  각 패키지의 최저 호환 버전을 해결한다.

lowest-direct:  직접 의존성의 최저 호환 버전을 해결하고, 전이 의존성의 최신 호환 버전을 해결한다.

--script script
현재 프로젝트 대신 지정된 Python 스크립트를 잠근다.

제공되면, uv는 스크립트(인라인 메타데이터 테이블을 기준으로, PEP 723을 준수)를 스크립트 자체와 인접한 .lock 파일에 잠근다.

--upgrade, -U
패키지 업그레이드를 허용하고, 기존 출력 파일에 고정된 버전을 무시한다. --refresh를 암시한다.

--upgrade-package, -P upgrade-package
특정 패키지에 대해 업그레이드를 허용하고, 기존 출력 파일에 고정된 버전을 무시한다. --refresh-package를 암시한다.

--verbose, -v
상세 출력을 사용한다.

RUST_LOG 환경 변수를 사용하여 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




## uv export

프로젝트의 lockfile을 다른 형식으로 내보낸다.

현재는 `requirements-txt`만 지원한다.

`--locked` 또는 `--frozen` 플래그를 제공하지 않으면, 프로젝트를 다시 잠금 처리한 후 내보낸다.

uv는 현재 디렉토리나 상위 디렉토리에서 프로젝트를 검색한다. 프로젝트를 찾지 못하면 uv는 오류와 함께 종료된다.

워크스페이스에서 작업하는 경우, 기본적으로 루트가 내보내진다. 그러나 `--package` 옵션을 사용해 특정 멤버를 선택할 수 있다.

사용법

uv export [OPTIONS]


옵션

--all-extras
모든 선택적 의존성을 포함한다.

--all-groups
모든 의존성 그룹에서 의존성을 포함한다.

--no-group을 사용해 특정 그룹을 제외할 수 있다.

--all-packages
전체 워크스페이스를 내보낸다.

모든 워크스페이스 멤버의 의존성이 내보내진 requirements 파일에 포함된다.

--extra, --group 또는 관련 옵션을 통해 지정된 추가 기능이나 그룹은 모든 워크스페이스 멤버에 적용된다.

--allow-insecure-host allow-insecure-host
호스트에 대한 안전하지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 안전한 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 터미널 또는 지원되는 TTY로 전송될 때만 색상 출력을 활성화한다.

always:  감지된 환경에 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
구성을 위해 사용할 uv.toml 파일의 경로.

uv 구성은 pyproject.toml 파일에 포함될 수 있지만, 이 컨텍스트에서는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정을 KEY=VALUE 쌍으로 지정한다.

--default-index default-index
기본 패키지 인덱스의 URL (기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식으로 구성된 로컬 디렉토리를 받는다.

이 플래그로 지정된 인덱스는 --index 플래그로 지정된 다른 모든 인덱스보다 낮은 우선순위를 가진다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 주어진 디렉토리로 변경한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z)와 시스템의 시간대에 따른 동일한 형식의 로컬 날짜(예: 2006-12-02)를 모두 받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra extra
지정된 추가 기능 이름에서 선택적 의존성을 포함한다.

여러 번 제공할 수 있다.

--extra-index-url extra-index-url
(더 이상 사용되지 않음: --index를 대신 사용) --index-url에 추가로 사용할 패키지 인덱스의 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식으로 구성된 로컬 디렉토리를 받는다.

이 플래그로 제공된 모든 인덱스는 --index-url로 지정된 인덱스(기본적으로 PyPI)보다 높은 우선순위를 가진다. 여러 --extra-index-url 플래그가 제공되면, 먼저 제공된 값이 더 높은 우선순위를 가진다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스에서 찾은 것 외에 후보 배포를 검색할 위치.

경로인 경우, 대상은 최상위 레벨에 휠 파일(.whl) 또는 소스 배포(예: .tar.gz 또는 .zip)를 포함하는 디렉토리여야 한다.

URL인 경우, 페이지는 위에서 설명한 형식을 준수하는 패키지 파일에 대한 링크의 평평한 목록을 포함해야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--fork-strategy fork-strategy
여러 Python 버전과 플랫폼에 걸쳐 주어진 패키지의 여러 버전을 선택할 때 사용할 전략.

기본적으로 uv는 지원되는 각 Python 버전(requires-python)에 대해 각 패키지의 최신 버전을 선택하면서, 플랫폼 간 선택된 버전 수를 최소화한다.

fewest 하에서는, uv는 각 패키지에 대해 선택된 버전 수를 최소화하며, 지원되는 Python 버전이나 플랫폼의 범위가 더 넓은 이전 버전을 선호한다.

UV_FORK_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


fewest:  각 패키지에 대해 선택된 버전 수를 최소화한다. 지원되는 Python 버전이나 플랫폼의 범위가 더 넓은 이전 버전을 선호한다.

requires-python:  지원되는 각 Python 버전에 대해 각 패키지의 최신 버전을 선택한다.

--format format
uv.lock을 내보낼 형식.

현재는 requirements-txt만 지원한다.

[기본값: requirements-txt]
가능한 값:


requirements-txt:  requirements.txt 형식으로 내보낸다.

--frozen
내보내기 전에 uv.lock을 업데이트하지 않는다.

uv.lock이 존재하지 않으면 uv는 오류와 함께 종료된다.

UV_FROZEN 환경 변수로도 설정할 수 있다.
--group group
지정된 의존성 그룹에서 의존성을 포함한다.

여러 번 제공할 수 있다.

--help, -h
이 명령에 대한 간결한 도움말을 표시한다.

--index index
기본 인덱스 외에 의존성을 해결할 때 사용할 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식으로 구성된 로컬 디렉토리를 받는다.

이 플래그로 제공된 모든 인덱스는 --default-index로 지정된 인덱스(기본적으로 PyPI)보다 높은 우선순위를 가진다. 여러 --index 플래그가 제공되면, 먼저 제공된 값이 더 높은 우선순위를 가진다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략.

기본적으로 uv는 주어진 패키지가 사용 가능한 첫 번째 인덱스에서 멈추고, 해당 첫 번째 인덱스에 있는 것만으로 해결을 제한한다(first-index). 이는 공격자가 동일한 이름으로 악성 패키지를 대체 인덱스에 업로드할 수 있는 "의존성 혼란" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  주어진 패키지 이름에 대해 첫 번째로 일치하는 인덱스의 결과만 사용한다.

unsafe-first-match:  모든 패키지 이름에 대해 모든 인덱스를 검색하고, 첫 번째 인덱스의 버전을 모두 소진한 후 다음 인덱스로 이동한다.

unsafe-best-match:  모든 패키지 이름에 대해 모든 인덱스를 검색하고, "가장 좋은" 버전을 선호한다. 패키지 버전이 여러 인덱스에 있으면 첫 번째 인덱스의 항목만 본다.

--index-url, -i index-url
(더 이상 사용되지 않음: --default-index를 대신 사용) Python 패키지 인덱스의 URL (기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식으로 구성된 로컬 디렉토리를 받는다.

이 플래그로 지정된 인덱스는 --extra-index-url 플래그로 지정된 다른 모든 인덱스보다 낮은 우선순위를 가진다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--keyring-provider keyring-provider
인덱스 URL에 대한 인증을 위해 keyring을 사용하려고 시도한다.

현재는 --keyring-provider subprocess만 지원되며, 이는 uv가 인증을 처리하기 위해 keyring CLI를 사용하도록 설정한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회를 위해 keyring을 사용하지 않는다.

subprocess:  자격 증명 조회를 위해 keyring 명령을 사용한다.

--link-mode link-mode
전역 캐시에서 패키지를 설치할 때 사용할 방법.

이 옵션은 소스 배포를 빌드할 때만 사용된다.

기본값은 macOS에서는 clone(Copy-on-Write), Linux와 Windows에서는 hardlink이다.

UV_LINK_MODE 환경 변수로도 설정할 수 있다.
가능한 값:


clone:  휠에서 site-packages 디렉토리로 패키지를 복제(즉, Copy-on-Write)한다.

copy:  휠에서 site-packages 디렉토리로 패키지를 복사한다.

hardlink:  휠에서 site-packages 디렉토리로 패키지를 하드 링크한다.

symlink:  휠에서 site-packages 디렉토리로 패키지를 심볼릭 링크한다.

--locked
uv.lock이 변경되지 않을 것이라고 단언한다.

lockfile이 최신 상태여야 한다. lockfile이 없거나 업데이트가 필요하면 uv는 오류와 함께 종료된다.

UV_LOCKED 환경 변수로도 설정할 수 있다.
--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 집합이며, uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우, 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-binary
미리 빌드된 휠을 설치하지 않는다.

지정된 패키지는 소스에서 빌드되어 설치된다. 해결자는 여전히 패키지 메타데이터를 추출하기 위해 미리 빌드된 휠을 사용할 수 있다.

UV_NO_BINARY 환경 변수로도 설정할 수 있다.
--no-binary-package no-binary-package
특정 패키지에 대해 미리 빌드된 휠을 설치하지 않는다.

UV_NO_BINARY_PACKAGE 환경 변수로도 설정할 수 있다.
--no-build
소스 배포를 빌드하지 않는다.

활성화되면, 해결은 임의의 Python 코드를 실행하지 않는다. 이미 빌드된 소스 배포의 캐시된 휠이 재사용되지만, 배포를 빌드해야 하는 작업은 오류와 함께 종료된다.

--no-build-isolation
소스 배포를 빌드할 때 격리를 비활성화한다.

PEP 518에 의해 지정된 빌드 의존성이 이미 설치되었다고 가정한다.

UV_NO_BUILD_ISOLATION 환경 변수로도 설정할 수 있다.
--no-build-isolation-package no-build-isolation-package
특정 패키지에 대해 소스 배포를 빌드할 때 격리를 비활성화한다.

패키지의 빌드 의존성이 PEP 518에 의해 이미 설치되었다고 가정한다.

--no-build-package no-build-package
특정 패키지에 대해 소스 배포를 빌드하지 않는다.

--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
구성 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 구성 파일은 현재 디렉토리, 상위 디렉토리 또는 사용자 구성 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-default-groups
기본 의존성 그룹을 무시한다.

uv는 기본적으로 tool.uv.default-groups에 정의된 그룹을 포함한다. 이 옵션은 해당 기능을 비활성화하지만, --group을 사용해 특정 그룹을 포함할 수 있다.

--no-dev
개발 의존성 그룹을 비활성화한다.

이 옵션은 --no-group dev의 별칭이다. 모든 기본 그룹을 비활성화하려면 --no-default-groups를 참조한다.

--no-editable
프로젝트와 모든 워크스페이스 멤버를 포함한 편집 가능한 의존성을 편집 불가능하게 설치한다.

--no-emit-package no-emit-package
주어진 패키지를 내보내지 않는다.

기본적으로 프로젝트의 모든 의존성이 내보내진 requirements 파일에 포함된다. --no-install-package 옵션을 사용해 특정 패키지를 제외할 수 있다.

--no-emit-project
현재 프로젝트를 내보내지 않는다.

기본적으로 현재 프로젝트는 모든 의존성과 함께 내보내진 requirements 파일에 포함된다. --no-emit-project 옵션을 사용해 프로젝트를 제외할 수 있지만, 모든 의존성은 여전히 포함된다.

--no-emit-workspace
루트 프로젝트를 포함한 모든 워크스페이스 멤버를 내보내지 않는다.

기본적으로 모든 워크스페이스 멤버와 그들의 의존성이 내보내진 requirements 파일에 포함된다. --no-emit-workspace 옵션을 사용해 모든 워크스페이스 멤버를 제외할 수 있지만, 그들의 의존성은 여전히 포함된다.

--no-extra no-extra
--all-extras가 제공된 경우, 지정된 선택적 의존성을 제외한다.

여러 번 제공할 수 있다.

--no-group no-group
지정된 의존성 그룹을 비활성화한다.

이 옵션은 기본 그룹, --all-groups, --group보다 항상 우선한다.

여러 번 제공할 수 있다.

--no-hashes
생성된 출력에서 해시를 생략한다.

--no-header
생성된 출력 파일 상단의 주석 헤더를 제외한다.

--no-index
레지스트리 인덱스(예: PyPI)를 무시하고, 직접 URL 의존성과 --find-links를 통해 제공된 것만 사용한다.

--no-progress
모든 진행 출력을 숨긴다.

예: 스피너나 진행 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--no-sources
의존성을 해결할 때 tool.uv.sources 테이블을 무시한다. 워크스페이스, Git, URL 또는 로컬 경로 소스를 사용하는 대신, 표준을 준수하고 게시 가능한 패키지 메타데이터에 대해 잠금 처리하는 데 사용된다.

--offline
네트워크 접근을 비활성화한다.

비활성화되면, uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--only-dev
개발 의존성 그룹만 포함한다.

프로젝트와 그 의존성은 제외된다.

이 옵션은 --only-group dev의 별칭이다. --no-default-groups를 암시한다.

--only-group only-group
지정된 의존성 그룹에서만 의존성을 포함한다.

프로젝트와 그 의존성은 제외된다.

여러 번 제공할 수 있다. --no-default-groups를 암시한다.

--output-file, -o output-file
내보낸 requirements를 주어진 파일에 쓴다.

--package package
워크스페이스에서 특정 패키지의 의존성을 내보낸다.

워크스페이스 멤버가 존재하지 않으면 uv는 오류와 함께 종료된다.

--prerelease prerelease
프리릴리스 버전을 고려할 때 사용할 전략.

기본적으로 uv는 프리릴리스만 게시하는 패키지와 선언된 지정자에 명시적 프리릴리스 마커가 포함된 첫 번째 의존성(if-necessary-or-explicit)에 대해 프리릴리스를 허용한다.

UV_PRERELEASE 환경 변수로도 설정할 수 있다.
가능한 값:


disallow:  모든 프리릴리스 버전을 허용하지 않는다.

allow:  모든 프리릴리스 버전을 허용한다.

if-necessary:  패키지의 모든 버전이 프리릴리스인 경우 프리릴리스 버전을 허용한다.

explicit:  첫 번째 의존성의 버전 요구 사항에 명시적 프리릴리스 마커가 포함된 경우 프리릴리스 버전을 허용한다.

if-necessary-or-explicit:  패키지의 모든 버전이 프리릴리스인 경우, 또는 패키지의 버전 요구 사항에 명시적 프리릴리스 마커가 포함된 경우 프리릴리스 버전을 허용한다.

--project project
주어진 프로젝트 디렉토리 내에서 명령을 실행한다.

모든 pyproject.toml, uv.toml, .python-version 파일은 프로젝트 루트에서 디렉토리 트리를 올라가며 검색되며, 프로젝트의 가상 환경(.venv)도 마찬가지이다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--prune prune
주어진 패키지를 의존성 트리에서 제거한다.

제거된 패키지는 내보내진 requirements 파일에서 제외되며, 제거된 패키지가 제거된 후 더 이상 필요하지 않은 의존성도 제외된다.

--python, -p python
해결 중에 사용할 Python 인터프리터.

Python 인터프리터는 휠이 없는 경우 패키지 메타데이터를 결정하기 위해 소스 배포를 빌드할 때 필요하다.

인터프리터는 또한 requires-python이 설정되지 않은 경우 최소 Python 버전의 대체 값으로 사용된다.

Python 검색 및 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참조한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 선호할지 여부.

기본적으로 uv는 관리하는 Python 버전을 사용하는 것을 선호한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선시하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용한다; 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 선호한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 선호한다.

only-system:  시스템 Python 설치만 사용한다; 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 인쇄하지 않는다.

--refresh
모든 캐시 데이터를 새로 고친다.

--refresh-package refresh-package
특정 패키지의 캐시 데이터를 새로 고친다.

--resolution resolution
주어진 패키지 요구 사항에 대해 서로 다른 호환 버전을 선택할 때 사용할 전략.

기본적으로 uv는 각 패키지의 최신 호환 버전(highest)을 사용한다.

UV_RESOLUTION 환경 변수로도 설정할 수 있다.
가능한 값:


highest:  각 패키지의 최신 호환 버전을 해결한다.

lowest:  각 패키지의 최저 호환 버전을 해결한다.

lowest-direct:  직접 의존성의 최저 호환 버전을 해결하고, 전이 의존성의 최신 호환 버전을 해결한다.

--script script
현재 프로젝트 대신 지정된 PEP 723 Python 스크립트의 의존성을 내보낸다.

제공된 경우, uv는 PEP 723에 따라 인라인 메타데이터 테이블을 기반으로 의존성을 해결한다.

--upgrade, -U
기존 출력 파일에 고정된 버전을 무시하고 패키지 업그레이드를 허용한다. --refresh를 암시한다.

--upgrade-package, -P upgrade-package
특정 패키지에 대해 기존 출력 파일에 고정된 버전을 무시하고 업그레이드를 허용한다. --refresh-package를 암시한다.

--verbose, -v
상세 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




## 의존성 트리 표시

프로젝트의 의존성 트리를 표시한다.

사용법

uv tree [OPTIONS]


옵션

--all-groups
모든 의존성 그룹의 의존성을 포함한다.

--no-group를 사용해 특정 그룹을 제외할 수 있다.

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크와 소스에서만 사용해야 한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉터리의 경로를 지정한다.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉터리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  터미널 또는 TTY에 출력할 때만 색상을 사용한다.

always:  환경에 상관없이 항상 색상을 사용한다.

never:  색상을 사용하지 않는다.

--config-file config-file
설정 파일 uv.toml의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정을 KEY=VALUE 쌍으로 지정한다.

--default-index default-index
기본 패키지 인덱스의 URL을 지정한다(기본값: <https://pypi.org/simple>).

PEP 503을 준수하는 리포지토리(단순 리포지토리 API) 또는 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 지정된 인덱스는 --index 플래그로 지정된 모든 인덱스보다 낮은 우선순위를 가진다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--depth, -d depth
의존성 트리의 최대 표시 깊이를 지정한다.

[기본값: 255]
--directory directory
명령어 실행 전에 주어진 디렉터리로 이동한다.

상대 경로는 주어진 디렉터리를 기준으로 해석된다.

프로젝트 루트 디렉터리만 변경하려면 --project를 참조한다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지만 후보로 고려한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z) 또는 시스템의 시간대에 맞는 로컬 날짜(예: 2006-12-02)를 받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra-index-url extra-index-url
(사용 중단: --index를 대신 사용) --index-url에 추가로 사용할 패키지 인덱스의 URL을 지정한다.

PEP 503을 준수하는 리포지토리(단순 리포지토리 API) 또는 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 제공된 모든 인덱스는 --index-url로 지정된 인덱스(기본값: PyPI)보다 높은 우선순위를 가진다. 여러 --extra-index-url 플래그가 제공되면, 먼저 제공된 값이 더 높은 우선순위를 가진다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스 외에 후보 배포판을 검색할 위치를 지정한다.

경로인 경우, 대상은 최상위에 휠 파일(.whl) 또는 소스 배포판(예: .tar.gz, .zip)이 포함된 디렉터리여야 한다.

URL인 경우, 페이지는 위에서 설명한 형식을 준수하는 패키지 파일에 대한 링크의 단순 목록을 포함해야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--fork-strategy fork-strategy
여러 Python 버전과 플랫폼에서 주어진 패키지의 여러 버전을 선택할 때 사용할 전략을 지정한다.

기본적으로 uv는 지원되는 Python 버전(requires-python)에 대해 각 패키지의 최신 버전을 선택하도록 최적화하며, 플랫폼 간 선택된 버전의 수를 최소화한다.

fewest를 사용하면, uv는 각 패키지에 대해 선택된 버전의 수를 최소화하며, 지원되는 Python 버전이나 플랫폼의 범위가 더 넓은 이전 버전을 선호한다.

UV_FORK_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


fewest:  각 패키지에 대해 선택된 버전의 수를 최소화한다. 지원되는 Python 버전이나 플랫폼의 범위가 더 넓은 이전 버전을 선호한다.

requires-python:  지원되는 Python 버전에 대해 각 패키지의 최신 버전을 선택하도록 최적화한다.

--frozen
프로젝트를 잠그지 않고 요구 사항을 표시한다.

잠금 파일이 없으면 uv는 오류와 함께 종료된다.

UV_FROZEN 환경 변수로도 설정할 수 있다.
--group group
지정된 의존성 그룹의 의존성을 포함한다.

여러 번 제공할 수 있다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다.

--index index
의존성을 해결할 때 사용할 URL을 기본 인덱스에 추가로 지정한다.

PEP 503을 준수하는 리포지토리(단순 리포지토리 API) 또는 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 제공된 모든 인덱스는 --default-index로 지정된 인덱스(기본값: PyPI)보다 높은 우선순위를 가진다. 여러 --index 플래그가 제공되면, 먼저 제공된 값이 더 높은 우선순위를 가진다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략을 지정한다.

기본적으로 uv는 주어진 패키지가 사용 가능한 첫 번째 인덱스에서 멈추고, 해당 첫 번째 인덱스에 있는 결과로만 해결을 제한한다(first-index). 이는 공격자가 대체 인덱스에 동일한 이름으로 악성 패키지를 업로드할 수 있는 "의존성 혼동" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  주어진 패키지 이름에 대해 첫 번째로 일치하는 인덱스의 결과만 사용한다.

unsafe-first-match:  모든 인덱스에서 모든 패키지 이름을 검색하며, 첫 번째 인덱스의 버전을 모두 소진한 후 다음 인덱스로 이동한다.

unsafe-best-match:  모든 인덱스에서 모든 패키지 이름을 검색하며, "가장 좋은" 버전을 선호한다. 패키지 버전이 여러 인덱스에 있는 경우, 첫 번째 인덱스의 항목만 확인한다.

--index-url, -i index-url
(사용 중단: --default-index를 대신 사용) Python 패키지 인덱스의 URL을 지정한다(기본값: <https://pypi.org/simple>).

PEP 503을 준수하는 리포지토리(단순 리포지토리 API) 또는 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 지정된 인덱스는 --extra-index-url 플래그로 지정된 모든 인덱스보다 낮은 우선순위를 가진다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--invert
주어진 패키지에 대한 역의존성을 표시한다. 이 플래그는 트리를 반전시켜 주어진 패키지를 의존하는 패키지를 표시한다.

--keyring-provider keyring-provider
인덱스 URL에 대한 인증을 위해 keyring을 사용하려고 시도한다.

현재는 --keyring-provider subprocess만 지원되며, 이는 uv가 keyring CLI를 사용해 인증을 처리하도록 설정한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회에 keyring을 사용하지 않는다.

subprocess:  자격 증명 조회에 keyring 명령어를 사용한다.

--link-mode link-mode
전역 캐시에서 패키지를 설치할 때 사용할 방법을 지정한다.

이 옵션은 소스 배포판을 빌드할 때만 사용된다.

기본값은 macOS에서는 clone(Copy-on-Write), Linux와 Windows에서는 hardlink이다.

UV_LINK_MODE 환경 변수로도 설정할 수 있다.
가능한 값:


clone:  휠에서 site-packages 디렉터리로 패키지를 복제한다(즉, Copy-on-Write).

copy:  휠에서 site-packages 디렉터리로 패키지를 복사한다.

hardlink:  휠에서 site-packages 디렉터리로 패키지를 하드 링크한다.

symlink:  휠에서 site-packages 디렉터리로 패키지를 심볼릭 링크한다.

--locked
uv.lock 파일이 변경되지 않을 것임을 단언한다.

잠금 파일이 최신 상태여야 한다. 잠금 파일이 없거나 업데이트가 필요하면 uv는 오류와 함께 종료된다.

UV_LOCKED 환경 변수로도 설정할 수 있다.
--native-tls
플랫폼의 네이티브 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 집합이며, uv에 포함되면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)에 의존하는 경우, 플랫폼의 네이티브 인증서 저장소를 사용하고 싶을 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-binary
미리 빌드된 휠을 설치하지 않는다.

주어진 패키지는 소스에서 빌드되고 설치된다. 리졸버는 여전히 패키지 메타데이터를 추출하기 위해 미리 빌드된 휠을 사용할 수 있다.

UV_NO_BINARY 환경 변수로도 설정할 수 있다.
--no-binary-package no-binary-package
특정 패키지에 대해 미리 빌드된 휠을 설치하지 않는다.

UV_NO_BINARY_PACKAGE 환경 변수로도 설정할 수 있다.
--no-build
소스 배포판을 빌드하지 않는다.

활성화되면, 리졸버는 임의의 Python 코드를 실행하지 않는다. 이미 빌드된 소스 배포판의 캐시된 휠은 재사용되지만, 배포판을 빌드해야 하는 작업은 오류와 함께 종료된다.

--no-build-isolation
소스 배포판을 빌드할 때 격리를 비활성화한다.

PEP 518에 의해 지정된 빌드 의존성이 이미 설치되어 있다고 가정한다.

UV_NO_BUILD_ISOLATION 환경 변수로도 설정할 수 있다.
--no-build-isolation-package no-build-isolation-package
특정 패키지에 대해 소스 배포판을 빌드할 때 격리를 비활성화한다.

패키지의 빌드 의존성이 PEP 518에 의해 이미 설치되어 있다고 가정한다.

--no-build-package no-build-package
특정 패키지에 대해 소스 배포판을 빌드하지 않는다.

--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉터리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉터리, 상위 디렉터리 또는 사용자 설정 디렉터리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-dedupe
반복된 의존성을 중복 제거하지 않는다. 일반적으로 패키지가 이미 의존성을 표시한 경우, 추가 발생 시 의존성을 다시 표시하지 않고 (*)를 포함해 이미 표시되었음을 나타낸다. 이 플래그는 중복된 의존성을 반복해서 표시한다.

--no-default-groups
기본 의존성 그룹을 무시한다.

uv는 기본적으로 tool.uv.default-groups에 정의된 그룹을 포함한다. 이 옵션은 해당 옵션을 비활성화하지만, --group으로 특정 그룹을 포함할 수 있다.

--no-dev
개발 의존성 그룹을 비활성화한다.

이 옵션은 --no-group dev의 별칭이다. 모든 기본 그룹을 비활성화하려면 --no-default-groups를 참조한다.

--no-group no-group
지정된 의존성 그룹을 비활성화한다.

이 옵션은 항상 기본 그룹, --all-groups, --group보다 우선한다.

여러 번 제공할 수 있다.

--no-index
레지스트리 인덱스(예: PyPI)를 무시하고, 직접 URL 의존성과 --find-links로 제공된 의존성만 사용한다.

--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 막대를 숨긴다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--no-sources
tool.uv.sources 테이블을 무시하고 의존성을 해결한다. 표준을 준수하고 게시 가능한 패키지 메타데이터에 대해 잠금을 설정하는 데 사용되며, 작업 공간, Git, URL 또는 로컬 경로 소스를 사용하지 않는다.

--offline
네트워크 액세스를 비활성화한다.

비활성화되면, uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--only-dev
개발 의존성 그룹만 포함한다.

프로젝트와 그 의존성은 제외된다.

이 옵션은 --only-group dev의 별칭이다. --no-default-groups를 암시한다.

--only-group only-group
지정된 의존성 그룹의 의존성만 포함한다.

프로젝트와 그 의존성은 제외된다.

여러 번 제공할 수 있다. --no-default-groups를 암시한다.

--outdated
트리의 각 패키지에 대해 사용 가능한 최신 버전을 표시한다.

--package package
지정된 패키지만 표시한다.

--prerelease prerelease
프리릴리스 버전을 고려할 때 사용할 전략을 지정한다.

기본적으로 uv는 프리릴리스만 출시하는 패키지와 선언된 지정자에 명시적 프리릴리스 마커가 포함된 1차 의존성에 대해 프리릴리스를 허용한다(if-necessary-or-explicit).

UV_PRERELEASE 환경 변수로도 설정할 수 있다.
가능한 값:


disallow:  모든 프리릴리스 버전을 허용하지 않는다.

allow:  모든 프리릴리스 버전을 허용한다.

if-necessary:  패키지의 모든 버전이 프리릴리스인 경우 프리릴리스 버전을 허용한다.

explicit:  버전 요구 사항에 명시적 프리릴리스 마커가 있는 1차 패키지에 대해 프리릴리스 버전을 허용한다.

if-necessary-or-explicit:  패키지의 모든 버전이 프리릴리스인 경우, 또는 패키지의 버전 요구 사항에 명시적 프리릴리스 마커가 있는 경우 프리릴리스 버전을 허용한다.

--project project
주어진 프로젝트 디렉터리 내에서 명령어를 실행한다.

모든 pyproject.toml, uv.toml, .python-version 파일은 프로젝트 루트에서 디렉터리 트리를 올라가며 검색되며, 프로젝트의 가상 환경(.venv)도 검색된다.

다른 명령줄 인수(예: 상대 경로)는 현재 작업 디렉터리를 기준으로 해석된다.

작업 디렉터리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--prune prune
의존성 트리 표시에서 주어진 패키지를 제거한다.

--python, -p python
잠금 및 필터링에 사용할 Python 인터프리터를 지정한다.

기본적으로 트리는 Python 인터프리터가 보고하는 플랫폼과 일치하도록 필터링된다. 모든 플랫폼에 대한 트리를 표시하려면 --universal을 사용하거나, --python-version 또는 --python-platform을 사용해 마커의 일부를 재정의한다.

Python 검색과 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참조한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-platform python-platform
트리를 필터링할 때 사용할 플랫폼을 지정한다.

예를 들어, Windows에서 설치할 때 포함될 의존성을 표시하려면 --platform windows를 전달한다.

"대상 삼중체"로 표현되며, CPU, 벤더 및 운영 체제 이름을 설명하는 문자열이다. 예: x86_64-unknown-linux-gnu 또는 aarch64-apple-darwin.

가능한 값:


windows:  x86_64-pc-windows-msvc의 별칭, Windows의 기본 대상.

linux:  x86_64-unknown-linux-gnu의 별칭, Linux의 기본 대상.

macos:  aarch64-apple-darwin의 별칭, macOS의 기본 대상.

x86_64-pc-windows-msvc:  64비트 x86 Windows 대상.

i686-pc-windows-msvc:  32비트 x86 Windows 대상.

x86_64-unknown-linux-gnu:  x86 Linux 대상. x86_64-manylinux_2_17과 동일.

aarch64-apple-darwin:  Apple Silicon 장치에서 볼 수 있는 ARM 기반 macOS 대상.

x86_64-apple-darwin:  x86 macOS 대상.

aarch64-unknown-linux-gnu:  ARM64 Linux 대상. aarch64-manylinux_2_17과 동일.

aarch64-unknown-linux-musl:  ARM64 Linux 대상.

x86_64-unknown-linux-musl:  x86_64 Linux 대상.

x86_64-manylinux2014:  manylinux2014 플랫폼에 대한 x86_64 대상. x86_64-manylinux_2_17과 동일.

x86_64-manylinux_2_17:  manylinux_2_17 플랫폼에 대한 x86_64 대상.

x86_64-manylinux_2_28:  manylinux_2_28 플랫폼에 대한 x86_64 대상.

x86_64-manylinux_2_31:  manylinux_2_31 플랫폼에 대한 x86_64 대상.

x86_64-manylinux_2_32:  manylinux_2_32 플랫폼에 대한 x86_64 대상.

x86_64-manylinux_2_33:  manylinux_2_33 플랫폼에 대한 x86_64 대상.

x86_64-manylinux_2_34:  manylinux_2_34 플랫폼에 대한 x86_64 대상.

x86_64-manylinux_2_35:  manylinux_2_35 플랫폼에 대한 x86_64 대상.

x86_64-manylinux_2_36:  manylinux_2_36 플랫폼에 대한 x86_64 대상.

x86_64-manylinux_2_37:  manylinux_2_37 플랫폼에 대한 x86_64 대상.

x86_64-manylinux_2_38:  manylinux_2_38 플랫폼에 대한 x86_64 대상.

x86_64-manylinux_2_39:  manylinux_2_39 플랫폼에 대한 x86_64 대상.

x86_64-manylinux_2_40:  manylinux_2_40 플랫폼에 대한 x86_64 대상.

aarch64-manylinux2014:  manylinux2014 플랫폼에 대한 ARM64 대상. aarch64-manylinux_2_17과 동일.

aarch64-manylinux_2_17:  manylinux_2_17 플랫폼에 대한 ARM64 대상.

aarch64-manylinux_2_28:  manylinux_2_28 플랫폼에 대한 ARM64 대상.

aarch64-manylinux_2_31:  manylinux_2_31 플랫폼에 대한 ARM64 대상.

aarch64-manylinux_2_32:  manylinux_2_32 플랫폼에 대한 ARM64 대상.

aarch64-manylinux_2_33:  manylinux_2_33 플랫폼에 대한 ARM64 대상.

aarch64-manylinux_2_34:  manylinux_2_34 플랫폼에 대한 ARM64 대상.

aarch64-manylinux_2_35:  manylinux_2_35 플랫폼에 대한 ARM64 대상.

aarch64-manylinux_2_36:  manylinux_2_36 플랫폼에 대한 ARM64 대상.

aarch64-manylinux_2_37:  manylinux_2_37 플랫폼에 대한 ARM64 대상.

aarch64-manylinux_2_38:  manylinux_2_38 플랫폼에 대한 ARM64 대상.

aarch64-manylinux_2_39:  manylinux_2_39 플랫폼에 대한 ARM64 대상.

aarch64-manylinux_2_40:  manylinux_2_40 플랫폼에 대한 ARM64 대상.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 선호할지 지정한다.

기본적으로 uv는 관리하는 Python 버전을 선호한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선시하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 선호한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 선호한다.

only-system:  시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--python-version python-version
트리를 필터링할 때 사용할 Python 버전을 지정한다.

예를 들어, Python 3.10에서 설치할 때 포함될 의존성을 표시하려면 --python-version 3.10을 전달한다.

기본값은 검색된 Python 인터프리터의 버전이다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--resolution resolution
주어진 패키지 요구 사항에 대해 서로 다른 호환 버전을 선택할 때 사용할 전략을 지정한다.

기본적으로 uv는 각 패키지의 최신 호환 버전을 사용한다(highest).

UV_RESOLUTION 환경 변수로도 설정할 수 있다.
가능한 값:


highest:  각 패키지의 최신 호환 버전을 해결한다.

lowest:  각 패키지의 최저 호환 버전을 해결한다.

lowest-direct:  직접 의존성의 최저 호환 버전을 해결하고, 전이 의존성의 최신 호환 버전을 해결한다.

--script script
현재 프로젝트 대신 지정된 PEP 723 Python 스크립트의 의존성 트리를 표시한다.

제공되면, uv는 PEP 723을 준수하여 인라인 메타데이터 테이블을 기반으로 의존성을 해결한다.

--universal
플랫폼 독립적인 의존성 트리를 표시한다.

현재 환경과 관련된 버전이 아닌, 모든 Python 버전과 플랫폼에 대해 해결된 패키지 버전을 표시한다.

각 패키지에 대해 여러 버전이 표시될 수 있다.

--upgrade, -U
패키지 업그레이드를 허용하고, 기존 출력 파일의 고정 버전을 무시한다. --refresh를 암시한다.

--upgrade-package, -P upgrade-package
특정 패키지에 대해 업그레이드를 허용하고, 기존 출력 파일의 고정 버전을 무시한다. --refresh-package를 암시한다.

--verbose, -v
자세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




## uv tool

Python 패키지에서 제공하는 명령어를 실행하고 설치한다.

사용법

uv tool [OPTIONS] <COMMAND>


명령어

uv tool run
Python 패키지에서 제공하는 명령어를 실행한다

uv tool install
Python 패키지에서 제공하는 명령어를 설치한다

uv tool upgrade
설치된 도구를 업그레이드한다

uv tool list
설치된 도구 목록을 확인한다

uv tool uninstall
도구를 제거한다

uv tool update-shell
도구 실행 파일 디렉토리가 PATH에 있는지 확인한다

uv tool dir
uv 도구 디렉토리의 경로를 보여준다




### uv tool run

Python 패키지가 제공하는 커맨드를 실행한다.

기본적으로 설치할 패키지 이름은 커맨드 이름과 동일하다고 가정한다.

커맨드 이름에 정확한 버전을 `@` 형식으로 포함할 수 있다. 예를 들어 `uv tool run ruff@0.3.0`과 같이 사용한다. 더 복잡한 버전 지정이 필요하거나 커맨드를 다른 패키지가 제공하는 경우 `--from` 옵션을 사용한다.

`uvx`는 Python을 실행하는 데 사용할 수 있다. 예를 들어 `uvx python` 또는 `uvx python@`과 같이 사용한다. 이 경우 Python 인터프리터가 격리된 가상 환경에서 시작된다.

이전에 `uv tool install`을 통해 도구를 설치한 경우, 버전을 요청하지 않거나 `--isolated` 플래그를 사용하지 않는 한 설치된 버전이 사용된다.

`uvx`는 `uv tool run`의 편의를 위한 별칭이며, 두 명령어의 동작은 동일하다.

커맨드를 제공하지 않으면 설치된 도구 목록이 표시된다.

패키지는 uv 캐시 디렉토리에 있는 임시 가상 환경에 설치된다.

사용법

uv tool run [OPTIONS] [COMMAND]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 안전하지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하므로 MITM 공격에 노출될 수 있다. 검증된 소스가 있는 안전한 네트워크에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 터미널 또는 TTY로 전송될 때만 색상 출력을 활성화

always:  환경에 관계없이 항상 색상 출력을 활성화

never:  색상 출력을 비활성화

--compile-bytecode
설치 후 Python 파일을 바이트코드로 컴파일한다.

기본적으로 uv는 Python 파일(.py)을 바이트코드(__pycache__/*.pyc)로 컴파일하지 않는다. 대신 모듈을 처음 임포트할 때 지연 컴파일을 수행한다. CLI 애플리케이션이나 Docker 컨테이너와 같이 시작 시간이 중요한 경우, 이 옵션을 활성화해 설치 시간을 늘리는 대신 시작 시간을 단축할 수 있다.

활성화하면 uv는 전체 site-packages 디렉토리(현재 작업으로 수정되지 않은 패키지 포함)를 일관적으로 처리한다. pip처럼 오류도 무시한다.

UV_COMPILE_BYTECODE 환경 변수로도 설정할 수 있다.
--config-file config-file
설정에 사용할 uv.toml 파일의 경로.

uv 설정은 pyproject.toml 파일에 포함할 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정을 KEY=VALUE 쌍으로 지정

--default-index default-index
기본 패키지 인덱스의 URL(기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 지정된 인덱스는 --index 플래그로 지정된 모든 인덱스보다 우선순위가 낮다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--directory directory
커맨드를 실행하기 전에 지정된 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해결된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z) 또는 시스템의 시간대에 맞는 로컬 날짜(예: 2006-12-02)를 입력받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra-index-url extra-index-url
(사용 중단: --index를 대신 사용) --index-url에 추가로 사용할 패키지 인덱스의 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 제공된 모든 인덱스는 --index-url로 지정된 인덱스(기본값은 PyPI)보다 우선순위가 높다. 여러 --extra-index-url 플래그를 제공할 경우, 먼저 제공된 값이 우선순위가 높다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스에서 찾은 것 외에 후보 배포판을 검색할 위치.

경로를 입력하면 대상은 최상위에 휠 파일(.whl) 또는 소스 배포판(예: .tar.gz 또는 .zip)이 포함된 디렉토리여야 한다.

URL을 입력하면 페이지에 위에서 설명한 형식의 패키지 파일에 대한 링크가 포함된 평면 목록이 있어야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--fork-strategy fork-strategy
여러 Python 버전과 플랫폼에서 주어진 패키지의 여러 버전을 선택할 때 사용할 전략.

기본적으로 uv는 각 지원되는 Python 버전(requires-python)에 대해 각 패키지의 최신 버전을 선택하는 동시에 플랫폼 간 선택된 버전 수를 최소화한다.

fewest를 선택하면 uv는 각 패키지에 대해 선택된 버전 수를 최소화하며, 더 넓은 범위의 지원 Python 버전 또는 플랫폼과 호환되는 이전 버전을 선호한다.

UV_FORK_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


fewest:  각 패키지에 대해 선택된 버전 수를 최소화하도록 최적화. 더 넓은 범위의 지원 Python 버전 또는 플랫폼과 호환되는 이전 버전을 선호

requires-python:  각 지원 Python 버전에 대해 각 패키지의 최신 지원 버전을 선택하도록 최적화

--from from
주어진 패키지를 사용해 커맨드를 제공한다.

기본적으로 패키지 이름은 커맨드 이름과 동일하다고 가정한다.

--help, -h
이 커맨드에 대한 간단한 도움말을 표시

--index index
종속성을 해결할 때 사용할 URL을 기본 인덱스에 추가한다.

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 제공된 모든 인덱스는 --default-index로 지정된 인덱스(기본값은 PyPI)보다 우선순위가 높다. 여러 --index 플래그를 제공할 경우, 먼저 제공된 값이 우선순위가 높다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략.

기본적으로 uv는 주어진 패키지가 사용 가능한 첫 번째 인덱스에서 중단하고, 해결을 해당 첫 번째 인덱스에 있는 것으로 제한한다(first-index). 이는 공격자가 악성 패키지를 대체 인덱스에 동일한 이름으로 업로드할 수 있는 "종속성 혼동" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  주어진 패키지 이름에 대해 첫 번째 인덱스에서 반환된 결과만 사용

unsafe-first-match:  모든 인덱스에서 모든 패키지 이름을 검색하고, 첫 번째 인덱스의 버전을 모두 검사한 후 다음 인덱스로 이동

unsafe-best-match:  모든 인덱스에서 모든 패키지 이름을 검색하고, "최적" 버전을 선호. 패키지 버전이 여러 인덱스에 있는 경우 첫 번째 인덱스의 항목만 확인

--index-url, -i index-url
(사용 중단: --default-index를 대신 사용) Python 패키지 인덱스의 URL(기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 지정된 인덱스는 --extra-index-url 플래그로 지정된 모든 인덱스보다 우선순위가 낮다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--isolated
이미 설치된 도구를 무시하고 격리된 가상 환경에서 도구를 실행

--keyring-provider keyring-provider
인덱스 URL에 대한 인증을 위해 keyring 사용을 시도한다.

현재 --keyring-provider subprocess만 지원되며, uv가 keyring CLI를 사용해 인증을 처리하도록 설정한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회에 keyring을 사용하지 않음

subprocess:  keyring 커맨드를 사용해 자격 증명 조회

--link-mode link-mode
전역 캐시에서 패키지를 설치할 때 사용할 방법.

기본값은 macOS에서는 clone(Copy-on-Write), Linux와 Windows에서는 hardlink이다.

UV_LINK_MODE 환경 변수로도 설정할 수 있다.
가능한 값:


clone:  휠에서 site-packages 디렉토리로 패키지를 복제(즉, Copy-on-Write)

copy:  휠에서 site-packages 디렉토리로 패키지를 복사

hardlink:  휠에서 site-packages 디렉토리로 패키지를 하드 링크

symlink:  휠에서 site-packages 디렉토리로 패키지를 심볼릭 링크

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 집합이며, uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-binary
미리 빌드된 휠을 설치하지 않는다.

주어진 패키지는 소스에서 빌드되어 설치된다. 리졸버는 여전히 패키지 메타데이터를 추출하기 위해 미리 빌드된 휠을 사용할 수 있다.

UV_NO_BINARY 환경 변수로도 설정할 수 있다.
--no-binary-package no-binary-package
특정 패키지에 대해 미리 빌드된 휠을 설치하지 않는다

UV_NO_BINARY_PACKAGE 환경 변수로도 설정할 수 있다.
--no-build
소스 배포판을 빌드하지 않는다.

활성화하면 임의의 Python 코드를 실행하지 않는다. 이미 빌드된 소스 배포판의 캐시된 휠이 재사용되지만, 배포판 빌드가 필요한 작업은 오류와 함께 종료된다.

--no-build-isolation
소스 배포판을 빌드할 때 격리를 비활성화한다.

PEP 518에 의해 지정된 빌드 종속성이 이미 설치되었다고 가정한다.

UV_NO_BUILD_ISOLATION 환경 변수로도 설정할 수 있다.
--no-build-isolation-package no-build-isolation-package
특정 패키지에 대해 소스 배포판을 빌드할 때 격리를 비활성화한다.

패키지의 빌드 종속성이 PEP 518에 의해 이미 설치되었다고 가정한다.

--no-build-package no-build-package
특정 패키지에 대해 소스 배포판을 빌드하지 않는다

--no-cache, -n
작업 기간 동안 임시 디렉토리를 사용해 캐시에서 읽거나 쓰지 않는다

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-index
레지스트리 인덱스(예: PyPI)를 무시하고 직접 URL 종속성과 --find-links로 제공된 종속성만 사용

--no-progress
모든 진행률 출력을 숨긴다.

예를 들어 스피너 또는 진행률 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python 자동 다운로드를 비활성화한다.

--no-sources
종속성을 해결할 때 tool.uv.sources 테이블을 무시한다. 작업 공간, Git, URL 또는 로컬 경로 소스를 사용하는 대신 표준 준수, 게시 가능한 패키지 메타데이터에 대해 잠그는 데 사용

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--prerelease prerelease
프리릴리스 버전을 고려할 때 사용할 전략.

기본적으로 uv는 프리릴리스만 출시하는 패키지와 선언된 지정자에 명시적 프리릴리스 마커가 포함된 1차 요구 사항(if-necessary-or-explicit)에 대해 프리릴리스를 허용한다.

UV_PRERELEASE 환경 변수로도 설정할 수 있다.
가능한 값:


disallow:  모든 프리릴리스 버전을 허용하지 않음

allow:  모든 프리릴리스 버전을 허용

if-necessary:  패키지의 모든 버전이 프리릴리스인 경우 프리릴리스 버전을 허용

explicit:  버전 요구 사항에 명시적 프리릴리스 마커가 있는 1차 패키지에 대해 프리릴리스 버전을 허용

if-necessary-or-explicit:  패키지의 모든 버전이 프리릴리스이거나 패키지의 버전 요구 사항에 명시적 프리릴리스 마커가 있는 경우 프리릴리스 버전을 허용

--project project
주어진 프로젝트 디렉토리 내에서 커맨드를 실행한다.

모든 pyproject.toml, uv.toml, .python-version 파일은 프로젝트 루트에서 디렉토리 트리를 올라가며 검색되며, 프로젝트의 가상 환경(.venv)도 마찬가지이다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해결된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python, -p python
실행 환경을 빌드할 때 사용할 Python 인터프리터.

Python 검색 및 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참조한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 여부.

기본적으로 uv는 관리하는 Python 버전을 우선적으로 사용한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용; 시스템 Python 설치를 사용하지 않음

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선

only-system:  시스템 Python 설치만 사용; 관리되는 Python 설치를 사용하지 않음

--quiet, -q
어떤 출력도 표시하지 않는다

--refresh
모든 캐시된 데이터를 새로 고친다

--refresh-package refresh-package
특정 패키지의 캐시된 데이터를 새로 고친다

--reinstall
이미 설치되었는지 여부에 관계없이 모든 패키지를 다시 설치한다. --refresh를 암시

--reinstall-package reinstall-package
이미 설치되었는지 여부에 관계없이 특정 패키지를 다시 설치한다. --refresh-package를 암시

--resolution resolution
주어진 패키지 요구 사항에 대해 호환 가능한 여러 버전 중 선택할 때 사용할 전략.

기본적으로 uv는 각 패키지의 최신 호환 버전(highest)을 사용한다.

UV_RESOLUTION 환경 변수로도 설정할 수 있다.
가능한 값:


highest:  각 패키지의 최고 호환 버전을 해결

lowest:  각 패키지의 최저 호환 버전을 해결

lowest-direct:  직접 종속성의 최저 호환 버전을 해결하고, 전이 종속성의 최고 호환 버전을 해결

--upgrade, -U
기존 출력 파일에 고정된 버전을 무시하고 패키지 업그레이드를 허용한다. --refresh를 암시

--upgrade-package, -P upgrade-package
기존 출력 파일에 고정된 버전을 무시하고 특정 패키지의 업그레이드를 허용한다. --refresh-package를 암시

--verbose, -v
상세 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시

--with with
주어진 패키지를 설치한 상태로 실행

--with-editable with-editable
주어진 패키지를 편집 가능 모드로 설치한 상태로 실행

프로젝트에서 사용할 경우, 이러한 종속성은 uv 도구의 환경 위에 별도의 임시 환경으로 계층화된다. 이러한 종속성은 지정된 종속성과 충돌할 수 있다.

--with-requirements with-requirements
주어진 requirements.txt 파일에 나열된 모든 패키지를 설치한 상태로 실행




### uv tool install

파이썬 패키지에서 제공하는 명령어를 설치한다.

패키지는 uv 도구 디렉토리 내의 격리된 가상 환경에 설치된다. 실행 파일은 XDG 표준에 따라 결정된 도구 실행 파일 디렉토리에 연결되며, `uv tool dir --bin` 명령어로 확인할 수 있다.

이전에 도구가 설치된 경우, 기존 도구는 일반적으로 교체된다.

사용법

uv tool install [OPTIONS] <PACKAGE>


인자

PACKAGE
명령어를 설치할 패키지



옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 보안 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 터미널 또는 TTY로 전송될 때만 색상 출력을 활성화한다.

always:  환경 감지와 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--compile-bytecode
설치 후 파이썬 파일을 바이트코드로 컴파일한다.

기본적으로 uv는 파이썬(.py) 파일을 바이트코드(__pycache__/*.pyc)로 컴파일하지 않는다. 대신 모듈이 처음 임포트될 때 지연 컴파일이 수행된다. CLI 애플리케이션이나 Docker 컨테이너와 같이 시작 시간이 중요한 경우, 이 옵션을 활성화해 더 긴 설치 시간을 감수하고 빠른 시작 시간을 얻을 수 있다.

활성화되면 uv는 일관성을 위해 전체 site-packages 디렉토리(현재 작업으로 수정되지 않는 패키지 포함)를 처리한다. pip와 마찬가지로 오류도 무시한다.

UV_COMPILE_BYTECODE 환경 변수로도 설정할 수 있다.
--config-file config-file
설정에 사용할 uv.toml 파일 경로.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정을 KEY=VALUE 쌍으로 지정한다.

--constraints, -c constraints
주어진 요구 사항 파일을 사용해 버전을 제한한다.

제약 파일은 requirements.txt와 유사한 파일로, 설치된 요구 사항의 버전만 제어한다. 그러나 제약 파일에 패키지를 포함해도 해당 패키지의 설치를 트리거하지 않는다.

이는 pip의 --constraint 옵션과 동일하다.

UV_CONSTRAINT 환경 변수로도 설정할 수 있다.
--default-index default-index
기본 패키지 인덱스의 URL(기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 인덱스는 --index 플래그로 지정된 모든 다른 인덱스보다 우선순위가 낮다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--directory directory
명령어 실행 전 주어진 디렉토리로 변경한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--editable, -e
대상 패키지를 편집 가능 모드로 설치해, 패키지 소스 디렉토리의 변경 사항이 재설치 없이 반영되도록 한다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z)와 시스템의 설정된 시간대에서 동일한 형식의 로컬 날짜(예: 2006-12-02)를 모두 받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할


### uv 도구 업그레이드

설치된 도구를 업그레이드한다.

도구가 버전 제약 조건과 함께 설치되었다면, 업그레이드 시에도 이를 준수한다. 원래 제공된 제약 조건을 넘어서 도구를 업그레이드하려면 `uv tool install`을 다시 사용한다.

도구가 특정 설정과 함께 설치되었다면, 업그레이드 시에도 이를 준수한다. 예를 들어, 설치 시 `--prereleases allow`가 제공되었다면, 업그레이드 시에도 이를 계속 준수한다.

사용법

uv tool upgrade [OPTIONS] <NAME>...


인자

NAME
업그레이드할 도구의 이름과 선택적 버전 지정자



옵션

--all
모든 도구를 업그레이드한다

--allow-insecure-host allow-insecure-host
호스트에 대한 안전하지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 안전한 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉터리의 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉터리의 위치를 보려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 갈 때만 색상 출력을 활성화한다

always:  감지된 환경과 관계없이 항상 색상 출력을 활성화한다

never:  색상 출력을 비활성화한다

--compile-bytecode
설치 후 Python 파일을 바이트코드로 컴파일한다.

기본적으로 uv는 Python(.py) 파일을 바이트코드(__pycache__/*.pyc)로 컴파일하지 않는다. 대신 모듈을 처음 임포트할 때 지연 컴파일을 수행한다. CLI 애플리케이션이나 Docker 컨테이너와 같이 시작 시간이 중요한 경우, 이 옵션을 활성화해 설치 시간을 늘리는 대신 시작 시간을 단축할 수 있다.

활성화하면 uv는 일관성을 위해 전체 site-packages 디렉터리(현재 작업으로 수정되지 않은 패키지 포함)를 처리한다. pip와 마찬가지로 오류도 무시한다.

UV_COMPILE_BYTECODE 환경 변수로도 설정할 수 있다.
--config-file config-file
구성을 위해 사용할 uv.toml 파일의 경로.

uv 구성은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정을 KEY=VALUE 쌍으로 지정한다

--default-index default-index
기본 패키지 인덱스의 URL(기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 제공된 인덱스는 --index 플래그로 지정된 모든 다른 인덱스보다 낮은 우선순위를 가진다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 주어진 디렉터리로 변경한다.

상대 경로는 주어진 디렉터리를 기준으로 해결된다.

프로젝트 루트 디렉터리만 변경하려면 --project를 참조한다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z)와 시스템의 구성된 시간대에서 동일한 형식의 로컬 날짜(예: 2006-12-02)를 모두 받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra-index-url extra-index-url
(더 이상 사용되지 않음: --index를 대신 사용) --index-url 외에 사용할 추가 패키지 인덱스 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 제공된 모든 인덱스는 --index-url로 지정된 인덱스(기본값은 PyPI)보다 높은 우선순위를 가진다. 여러 --extra-index-url 플래그가 제공되면, 먼저 제공된 값이 더 높은 우선순위를 가진다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스 외에 후보 배포판을 검색할 위치.

경로인 경우, 대상은 최상위 레벨에 휠 파일(.whl) 또는 소스 배포판(예: .tar.gz 또는 .zip)이 포함된 디렉터리여야 한다.

URL인 경우, 페이지는 위에서 설명한 형식을 준수하는 패키지 파일에 대한 링크의 평면 목록을 포함해야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--fork-strategy fork-strategy
여러 Python 버전과 플랫폼에서 주어진 패키지의 여러 버전을 선택할 때 사용할 전략.

기본적으로 uv는 각 지원되는 Python 버전(requires-python)에 대해 각 패키지의 최신 버전을 선택하면서 플랫폼 간 선택된 버전 수를 최소화한다.

fewest에서는 각 패키지에 대해 선택된 버전 수를 최소화하며, 더 넓은 범위의 지원되는 Python 버전 또는 플랫폼과 호환되는 이전 버전을 선호한다.

UV_FORK_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


fewest:  각 패키지에 대해 선택된 버전 수를 최소화한다. 더 넓은 범위의 지원되는 Python 버전 또는 플랫폼과 호환되는 이전 버전을 선호한다

requires-python:  각 지원되는 Python 버전에 대해 최신 지원 버전을 선택한다

--help, -h
이 명령에 대한 간결한 도움말을 표시한다

--index index
기본 인덱스 외에 종속성을 해결할 때 사용할 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 제공된 모든 인덱스는 --default-index로 지정된 인덱스(기본값은 PyPI)보다 높은 우선순위를 가진다. 여러 --index 플래그가 제공되면, 먼저 제공된 값이 더 높은 우선순위를 가진다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략.

기본적으로 uv는 주어진 패키지 이름에 대해 첫 번째 인덱스에서 사용 가능한 것을 멈추고, 첫 번째 인덱스에 있는 것만으로 해결을 제한한다(first-index). 이는 공격자가 대체 인덱스에 동일한 이름으로 악성 패키지를 업로드할 수 있는 "종속성 혼동" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  주어진 패키지 이름에 대해 첫 번째 인덱스에서 반환된 결과만 사용한다

unsafe-first-match:  모든 인덱스에서 모든 패키지 이름을 검색하며, 첫 번째 인덱스의 버전을 모두 소진한 후 다음 인덱스로 이동한다

unsafe-best-match:  모든 인덱스에서 모든 패키지 이름을 검색하며, "최고" 버전을 선호한다. 패키지 버전이 여러 인덱스에 있는 경우, 첫 번째 인덱스의 항목만 본다

--index-url, -i index-url
(더 이상 사용되지 않음: --default-index를 대신 사용) Python 패키지 인덱스의 URL(기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 제공된 인덱스는 --extra-index-url 플래그로 지정된 모든 다른 인덱스보다 낮은 우선순위를 가진다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--keyring-provider keyring-provider
인덱스 URL에 대한 인증을 위해 keyring을 사용하려고 시도한다.

현재는 --keyring-provider subprocess만 지원되며, 이는 uv가 keyring CLI를 사용해 인증을 처리하도록 구성한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회에 keyring을 사용하지 않는다

subprocess:  자격 증명 조회에 keyring 명령을 사용한다

--link-mode


### uv 도구 목록

설치된 도구 목록 확인

사용법

uv tool list [OPTIONS]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 보안되지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력한다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소와 대조되지 않는다. --allow-insecure-host는 SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리 경로를 지정한다.

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  터미널 또는 TTY에 출력할 때만 색상 출력을 활성화한다.

always:  환경 감지와 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정 파일로 사용할 uv.toml 파일의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함할 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령어 실행 전 주어진 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, uv에 포함되면 이식성과 성능(특히 macOS에서)이 향상된다.

하지만 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 기업 신뢰 루트(예: 필수 프록시)를 사용하려면 플랫폼의 기본 인증서 저장소를 사용해야 할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어 스피너나 진행률 표시줄 등이다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에 있는 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
주어진 프로젝트 디렉토리 내에서 명령어를 실행한다.

모든 pyproject.toml, uv.toml, .python-version 파일은 프로젝트 루트에서 디렉토리 트리를 따라 검색되며, 프로젝트의 가상 환경(.venv)도 마찬가지이다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--quiet, -q
출력을 표시하지 않는다.

--show-paths
각 도구 환경과 설치된 실행 파일의 경로를 표시할지 여부를 지정한다.

--show-version-specifiers
각 도구를 설치할 때 사용된 버전 지정자를 표시할지 여부를 지정한다.

--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv 도구 제거

도구를 제거한다.

사용법

uv tool uninstall [OPTIONS] <NAME>...


인자

NAME
제거할 도구의 이름

옵션

--all
모든 도구를 제거한다
--allow-insecure-host allow-insecure-host
호스트에 대한 보안되지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 보안 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수를 통해 설정할 수도 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수를 통해 설정할 수도 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전달될 때만 색상 출력을 활성화한다

always:  환경 감지 여부와 관계없이 항상 색상 출력을 활성화한다

never:  색상 출력을 비활성화한다

--config-file config-file
설정에 사용할 uv.toml 파일의 경로.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수를 통해 설정할 수도 있다.
--directory directory
명령어 실행 전에 주어진 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참고한다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, uv에 포함되면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 기업 신뢰 루트(예: 필수 프록시)를 사용해야 할 때는 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수를 통해 설정할 수도 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다

UV_NO_CACHE 환경 변수를 통해 설정할 수도 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수를 통해 설정할 수도 있다.
--no-progress
모든 진행 상태 출력을 숨긴다.

예를 들어, 스피너나 진행 표시줄 등.

UV_NO_PROGRESS 환경 변수를 통해 설정할 수도 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬 파일만 사용한다.

UV_OFFLINE 환경 변수를 통해 설정할 수도 있다.
--project project
주어진 프로젝트 디렉토리 내에서 명령어를 실행한다.

프로젝트 루트에서 디렉토리 트리를 탐색하며 pyproject.toml, uv.toml, .python-version 파일과 프로젝트의 가상 환경(.venv)을 검색한다.

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참고한다.

이 설정은 uv pip 인터페이스에서 사용할 때는 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 선택한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 그러나 관리되는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수를 통해 설정할 수도 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용한다; 시스템 Python 설치를 사용하지 않는다

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선한다

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선한다

only-system:  시스템 Python 설치만 사용한다; 관리되는 Python 설치를 사용하지 않는다

--quiet, -q
어떤 출력도 표시하지 않는다

--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다




### uv tool update-shell

도구 실행 파일 디렉토리가 `PATH`에 있는지 확인한다.

만약 도구 실행 파일 디렉토리가 `PATH`에 없다면, uv는 해당 디렉토리를 관련 셸 설정 파일에 추가하려고 시도한다.

셸 설정 파일에 이미 실행 파일 디렉토리를 `PATH`에 추가하는 내용이 포함되어 있지만, 실제로 디렉토리가 `PATH`에 없다면 uv는 오류와 함께 종료된다.

도구 실행 파일 디렉토리는 XDG 표준에 따라 결정되며, `uv tool dir --bin` 명령어로 확인할 수 있다.

사용법

uv tool update-shell [OPTIONS]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소와 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 보안 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로를 지정한다.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전송될 때만 색상 출력을 활성화한다.

always:  환경 감지와 상관없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정에 사용할 uv.toml 파일의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령어를 실행하기 전에 주어진 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참고한다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, 이를 uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

하지만 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리, 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄이 숨겨진다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화된 경우, uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
주어진 프로젝트 디렉토리 내에서 명령어를 실행한다.

프로젝트 루트에서 디렉토리 트리를 따라 올라가면서 pyproject.toml, uv.toml, .python-version 파일을 검색하고, 프로젝트의 가상 환경(.venv)도 찾는다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참고한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선시할지 지정한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 하지만 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선시하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선시한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선시한다.

only-system:  시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 설정할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv tool dir

uv 도구 디렉토리의 경로를 표시한다.

도구 디렉토리는 설치된 도구의 환경과 메타데이터를 저장하는 데 사용된다.

기본적으로 도구는 Unix 시스템에서는 `$XDG_DATA_HOME/uv/tools` 또는 `$HOME/.local/share/uv/tools`에, Windows에서는 `%APPDATA%\uv\data\tools`에 저장된다.

도구 설치 디렉토리는 `$UV_TOOL_DIR`로 재정의할 수 있다.

대신 uv가 실행 파일을 설치하는 디렉토리를 확인하려면 `--bin` 플래그를 사용한다.

사용법

uv tool dir [OPTIONS]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크와 검증된 소스에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--bin
uv tool이 실행 파일을 설치할 디렉토리를 표시한다.

기본적으로 uv tool dir는 도구의 Python 환경 자체가 설치된 디렉토리를 보여주며, 연결된 실행 파일이 포함된 디렉토리는 보여주지 않는다.

도구 실행 파일 디렉토리는 XDG 표준에 따라 결정되며, 다음 환경 변수를 우선순위로 사용한다:


$UV_TOOL_BIN_DIR

$XDG_BIN_HOME

$XDG_DATA_HOME/../bin

$HOME/.local/bin


--cache-dir cache-dir
캐시 디렉토리의 경로를 지정한다.

기본값은 macOS와 Linux에서는 `$XDG_CACHE_HOME/uv` 또는 `$HOME/.cache/uv`, Windows에서는 `%LOCALAPPDATA%\uv\cache`이다.

캐시 디렉토리의 위치를 확인하려면 `uv cache dir`를 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  터미널 또는 TTY에 출력할 때만 색상 출력을 활성화

always:  환경과 관계없이 항상 색상 출력을 활성화

never:  색상 출력을 비활성화

--config-file config-file
설정에 사용할 uv.toml 파일의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함할 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령어 실행 전에 지정된 디렉토리로 변경한다.

상대 경로는 지정된 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 결정한다.

기본적으로 uv는 내장된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla에서 제공하는 신뢰할 수 있는 루트 인증서 집합이며, 이를 uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

하지만 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 기업 신뢰 루트(예: 필수 프록시)를 사용하려는 경우 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예: 스피너 또는 진행률 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
지정된 프로젝트 디렉토리 내에서 명령어를 실행한다.

모든 pyproject.toml, uv.toml, .python-version 파일은 프로젝트 루트에서 디렉토리 트리를 탐색하여 발견되며, 프로젝트의 가상 환경(.venv)도 마찬가지이다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 결정한다.

기본적으로 uv는 자신이 관리하는 Python 버전을 우선 사용한다. 하지만 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용; 시스템 Python 설치를 사용하지 않음

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선

only-system:  시스템 Python 설치만 사용; 관리되는 Python 설치를 사용하지 않음

--quiet, -q
어떤 출력도 표시하지 않는다

--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용하여 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다




## uv 파이썬

파이썬 버전과 설치를 관리한다.

일반적으로 uv는 먼저 가상 환경에서 파이썬을 찾는다. 현재 작업 디렉토리나 상위 디렉토리의 `.venv` 디렉토리에 활성화된 가상 환경이 있는지 확인한다. 가상 환경이 필요하지 않다면, uv는 파이썬 인터프리터를 검색한다. 파이썬 인터프리터는 `PATH` 환경 변수에서 파이썬 실행 파일을 찾아 발견한다.

윈도우에서는 레지스트리에서도 파이썬 실행 파일을 검색한다.

기본적으로 uv는 특정 버전의 파이썬을 찾지 못하면 다운로드한다. 이 동작은 `--no-python-downloads` 플래그나 `python-downloads` 설정으로 비활성화할 수 있다.

`--python` 옵션을 사용하면 다른 인터프리터를 요청할 수 있다.

다음과 같은 파이썬 버전 요청 형식을 지원한다:

- `` 예: `3`, `3.12`, `3.12.3`
- `` 예: `>=3.12,<3.13`
- `` 예: `cpython` 또는 `cp`
- `@` 예: `cpython@3.12`
- `` 예: `cpython3.12` 또는 `cp312`
- `` 예: `cpython>=3.12,<3.13`
- `----` 예: `cpython-3.12.3-macos-aarch64-none`

또한, 특정 시스템 파이썬 인터프리터를 다음과 같이 요청할 수 있다:

- `` 예: `/opt/homebrew/bin/python3`
- `` 예: `mypython3`
- `` 예: `/some/environment/`

`--python` 옵션을 사용하면 일반적인 검색 규칙이 적용되지만, 발견된 인터프리터가 요청과 호환되는지 확인한다. 예를 들어 `pypy`를 요청하면, uv는 먼저 가상 환경에 PyPy 인터프리터가 있는지 확인한 후, 경로에 있는 각 실행 파일이 PyPy 인터프리터인지 확인한다.

uv는 CPython, PyPy, GraalPy 인터프리터를 지원한다. 지원되지 않는 인터프리터는 검색 과정에서 건너뛴다. 지원되지 않는 인터프리터 구현을 요청하면 uv는 오류와 함께 종료된다.

사용법

uv python [OPTIONS] <COMMAND>


커맨드

uv python list
사용 가능한 파이썬 설치 목록을 표시한다

uv python install
파이썬 버전을 다운로드하고 설치한다

uv python find
파이썬 설치를 검색한다

uv python pin
특정 파이썬 버전으로 고정한다

uv python dir
uv 파이썬 설치 디렉토리를 표시한다

uv python uninstall
파이썬 버전을 제거한다




### uv python list

사용 가능한 Python 설치 목록을 나열한다.

기본적으로 설치된 Python 버전과 지원되는 각 Python 주요 버전의 최신 패치 버전 다운로드가 표시된다.

표시되는 버전은 `--python-preference` 옵션에 따라 필터링된다. 예를 들어 `only-system`을 사용하면 관리되는 Python 버전이 표시되지 않는다.

모든 사용 가능한 패치 버전을 보려면 `--all-versions`를 사용한다.

다운로드 가능한 항목을 제외하고 설치된 버전만 보려면 `--only-installed`를 사용한다.

사용법

uv python list [OPTIONS]


옵션

--all-arches
모든 아키텍처에 대한 Python 다운로드를 나열한다.

기본적으로 현재 아키텍처에 대한 다운로드만 표시된다.

--all-platforms
모든 플랫폼에 대한 Python 다운로드를 나열한다.

기본적으로 현재 플랫폼에 대한 다운로드만 표시된다.

--all-versions
이전 패치 버전을 포함한 모든 Python 버전을 나열한다.

기본적으로 각 마이너 버전의 최신 패치 버전만 표시된다.

--allow-insecure-host allow-insecure-host
호스트에 대한 보안되지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크와 검증된 소스에서만 사용해야 한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로를 지정한다.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto: 출력이 색상을 지원하는 터미널이나 TTY로 전송될 때만 색상 출력을 활성화한다.

always: 감지된 환경에 관계없이 항상 색상 출력을 활성화한다.

never: 색상 출력을 비활성화한다.

--config-file config-file
구성을 위해 사용할 uv.toml 파일의 경로를 지정한다.

uv 구성은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 주어진 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--help, -h
이 명령에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합으로, uv에 포함되면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 기업 신뢰 루트(예: 필수 프록시)를 사용해야 할 때 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
구성 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 구성 파일은 현재 디렉토리, 상위 디렉토리 또는 사용자 구성 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어 스피너나 진행 막대가 표시되지 않는다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 액세스를 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--only-downloads
Python 다운로드만 표시하고 설치된 배포판은 제외한다.

기본적으로 현재 플랫폼에 대한 다운로드 가능 항목이 표시된다.

--only-installed
설치된 Python 버전만 표시하고 다운로드 가능 항목은 제외한다.

기본적으로 현재 플랫폼에 대한 다운로드 가능 항목이 표시된다.

--output-format output-format
출력 형식을 선택한다.

[기본값: text]
가능한 값:


text: 일반 텍스트(사람용)

json: JSON(컴퓨터용)

--project project
주어진 프로젝트 디렉토리 내에서 명령을 실행한다.

프로젝트 루트에서 디렉토리 트리를 따라 올라가면서 모든 pyproject.toml, uv.toml, .python-version 파일이 검색된다. 프로젝트의 가상 환경(.venv)도 검색된다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때는 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 지정한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 그러나 관리되는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 사용하면 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed: 관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed: 시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

system: 관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system: 시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
출력을 표시하지 않는다.

--show-urls
사용 가능한 Python 다운로드의 URL을 표시한다.

기본적으로 <download available>로 표시된다.

--verbose, -v
자세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용하여 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv python install

Python 버전을 다운로드하고 설치한다.

CPython과 PyPy를 지원한다. CPython 배포판은 Astral의 `python-build-standalone` 프로젝트에서 다운로드한다. PyPy 배포판은 `python.org`에서 다운로드한다. 사용 가능한 Python 버전은 각 uv 릴리스와 함께 번들로 제공된다. 새로운 Python 버전을 설치하려면 uv를 업그레이드해야 할 수 있다.

Python 버전은 uv Python 디렉토리에 설치되며, `uv python dir` 명령으로 이 디렉토리를 확인할 수 있다.

`python` 실행 파일은 전역적으로 제공되지 않는다. 관리되는 Python 버전은 uv 커맨드나 활성화된 가상 환경에서만 사용된다. Python 실행 파일을 `PATH`에 추가하는 실험적인 기능이 있으며, `--preview` 플래그를 사용해 이 동작을 활성화할 수 있다.

여러 Python 버전을 요청할 수 있다.

지원되는 요청 형식을 보려면 `uv help python`을 참고한다.

사용법

uv python install [OPTIONS] [TARGETS]...


인자

TARGETS
설치할 Python 버전.

인자가 제공되지 않으면 요청된 Python 버전은 UV_PYTHON 환경 변수, .python-versions 또는 .python-version 파일에서 읽어온다. 위의 항목이 모두 없으면 uv가 설치된 Python 버전이 있는지 확인한다. 없으면 최신 안정 버전의 Python을 설치한다.

지원되는 요청 형식을 보려면 uv python을 참고한다.



옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소와 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 터미널이나 TTY로 전송될 때만 색상 출력을 활성화

always:  환경 감지와 관계없이 항상 색상 출력을 활성화

never:  색상 출력을 비활성화

--config-file config-file
구성에 사용할 uv.toml 파일 경로.

uv 구성은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--default
기본 Python 버전으로 사용한다.

기본적으로 python{major}.{minor} 실행 파일만 설치된다(예: python3.10). --default 플래그를 사용하면 python{major}(예: python3)와 python 실행 파일도 설치된다.

대체 Python 변형은 여전히 태그를 포함한다. 예를 들어, 3.13+freethreaded를 --default로 설치하면 python3t와 pythont가 포함되며, python3와 python은 포함되지 않는다.

여러 Python 버전을 요청하면 uv는 오류와 함께 종료된다.

--directory directory
명령 실행 전 주어진 디렉토리로 변경한다.

상대 경로는 주어진 디렉토리를 기준으로 해결된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참고한다.

--force, -f
설치 중 기존 Python 실행 파일을 교체한다.

기본적으로 uv는 관리하지 않는 실행 파일을 교체하지 않는다.

--reinstall을 암시한다.

--help, -h
이 명령에 대한 간결한 도움말을 표시한다

--install-dir, -i install-dir
Python 설치를 저장할 디렉토리.

이 옵션을 사용하면 이후 작업에서 Python 설치를 발견하기 위해 UV_PYTHON_INSTALL_DIR을 설정해야 한다.

현재 Python 설치 디렉토리를 확인하려면 uv python dir을 실행한다. 기본값은 ~/.local/share/uv/python이다.

UV_PYTHON_INSTALL_DIR 환경 변수로도 설정할 수 있다.
--mirror mirror
Python 설치를 다운로드할 소스 URL을 설정한다.

제공된 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에서 사용된다.

file:// URL 스키마를 사용해 로컬 디렉토리에서 배포판을 읽을 수 있다.

UV_PYTHON_INSTALL_MIRROR 환경 변수로도 설정할 수 있다.
--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

하지만 경우에 따라 플랫폼의 기본 인증서 저장소를 사용하고 싶을 수 있다. 특히 시스템의 인증서 저장소에 포함된 기업 신뢰 루트(예: 필수 프록시)를 사용하는 경우에 유용하다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
구성 파일(pyproject.toml, uv.toml)을 탐색하지 않는다.

일반적으로 구성 파일은 현재 디렉토리, 상위 디렉토리 또는 사용자 구성 디렉토리에서 탐색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예: 스피너나 진행률 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화되면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
주어진 프로젝트 디렉토리 내에서 명령을 실행한다.

프로젝트 루트에서 디렉토리 트리를 올라가며 pyproject.toml, uv.toml, .python-version 파일을 탐색하고, 프로젝트의 가상 환경(.venv)도 탐색한다.

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해결된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참고한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--pypy-mirror pypy-mirror
PyPy 설치를 다운로드할 소스 URL을 설정한다.

제공된 URL은 https://downloads.python.org/pypy를 대체한다. 예를 들어, https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2에서 사용된다.

file:// URL 스키마를 사용해 로컬 디렉토리에서 배포판을 읽을 수 있다.

UV_PYPY_INSTALL_MIRROR 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv 관리 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 설정한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 하지만 uv 관리 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션은 시스템 Python 설치를 우선하거나 무시할 수 있게 한다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리 Python 설치만 사용; 시스템 Python 설치를 사용하지 않음

managed:  시스템 Python 설치보다 관리 Python 설치를 우선

system:  관리 Python 설치보다 시스템 Python 설치를 우선

only-system:  시스템 Python 설치만 사용; 관리 Python 설치를 사용하지 않음

--quiet, -q
어떤 출력도 표시하지 않는다

--reinstall, -r
요청한 Python 버전이 이미 설치된 경우 재설치한다.

기본적으로 uv는 버전이 이미 설치된 경우 성공적으로 종료한다.

--verbose, -v
상세 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다




### uv python find

Python 설치를 검색한다.

Python 실행 파일의 경로를 표시한다.

지원되는 요청 형식과 검색 동작에 대한 자세한 내용은 `uv help python`을 참조한다.

사용법

uv python find [OPTIONS] [REQUEST]


인자

REQUEST
Python 요청.

지원되는 요청 형식은 uv python을 참조한다.



옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 보안 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로.

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto: 출력이 색상을 지원하는 터미널이나 TTY로 향할 때만 색상 출력을 활성화한다.

always: 감지된 환경과 관계없이 항상 색상 출력을 활성화한다.

never: 색상 출력을 비활성화한다.

--config-file config-file
구성을 위해 사용할 uv.toml 파일의 경로.

uv 구성은 pyproject.toml 파일에 포함될 수 있지만, 이 컨텍스트에서는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령어 실행 전에 주어진 디렉토리로 변경한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, 이를 uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 기업 신뢰 루트(예: 필수 프록시)를 사용하려는 경우, 플랫폼의 기본 인증서 저장소를 사용하고 싶을 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
구성 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 구성 파일은 현재 디렉토리, 상위 디렉토리 또는 사용자 구성 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-project
프로젝트나 작업 공간을 검색하지 않는다.

그렇지 않으면 요청이 제공되지 않을 때 현재 디렉토리나 상위 디렉토리의 프로젝트 Python 요구 사항이 사용된다.

--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화되면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
주어진 프로젝트 디렉토리 내에서 명령어를 실행한다.

모든 pyproject.toml, uv.toml, .python-version 파일은 프로젝트 루트부터 디렉토리 트리를 따라 검색되며, 프로젝트의 가상 환경(.venv)도 마찬가지이다.

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 여부.

기본적으로 uv는 자신이 관리하는 Python 버전을 우선 사용한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed: 관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed: 관리되는 Python 설치를 시스템 Python 설치보다 우선한다.

system: 시스템 Python 설치를 관리되는 Python 설치보다 우선한다.

only-system: 시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--system
시스템 Python 인터프리터만 찾는다.

기본적으로 uv는 활성 가상 환경이나 현재 작업 디렉토리 또는 상위 디렉토리의 가상 환경에 있는 Python 인터프리터를 포함하여 사용할 첫 번째 Python 인터프리터를 보고한다.

--system 옵션은 uv에게 가상 환경 Python 인터프리터를 건너뛰고 시스템 경로로 검색을 제한하도록 지시한다.

UV_SYSTEM_PYTHON 환경 변수로도 설정할 수 있다.
--verbose, -v
상세 출력을 사용한다.

RUST_LOG 환경 변수를 사용하여 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv python pin

특정 Python 버전을 고정한다.

고정된 Python 버전을 `.python-version` 파일에 기록한다. 이 파일은 다른 uv 커맨드에서 필요한 Python 버전을 결정할 때 사용된다.

버전을 제공하지 않으면 uv는 기존 `.python-version` 파일을 찾아 현재 고정된 버전을 표시한다. `.python-version` 파일이 없으면 uv는 오류와 함께 종료된다.

지원되는 요청 형식을 보려면 `uv help python`을 참조한다.

사용법

uv python pin [OPTIONS] [REQUEST]


인자

REQUEST
Python 버전 요청.

uv는 `.python-version` 파일을 읽는 다른 도구(예: `pyenv`)보다 더 많은 형식을 지원한다. 이러한 도구와의 호환성이 필요하면 `cpython@3.10`과 같은 복잡한 요청 대신 버전 번호만 사용한다.

요청을 제공하지 않으면 현재 고정된 버전을 표시한다.

지원되는 요청 형식을 보려면 uv python을 참조한다.



옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: `localhost`), 호스트-포트 쌍(예: `localhost:8080`), 또는 URL(예: `https://localhost`)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 보안 네트워크에서만 `--allow-insecure-host`를 사용한다.

`UV_INSECURE_HOST` 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리 경로.

기본값은 macOS와 Linux에서는 `$XDG_CACHE_HOME/uv` 또는 `$HOME/.cache/uv`, Windows에서는 `%LOCALAPPDATA%\uv\cache`이다.

캐시 디렉토리 위치를 보려면 `uv cache dir`을 실행한다.

`UV_CACHE_DIR` 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


`auto`: 출력이 색상을 지원하는 터미널 또는 TTY로 향할 때만 색상 출력을 활성화한다.

`always`: 감지된 환경에 관계없이 항상 색상 출력을 활성화한다.

`never`: 색상 출력을 비활성화한다.

--config-file config-file
설정에 사용할 `uv.toml` 파일 경로.

uv 설정은 `pyproject.toml` 파일에 포함될 수 있지만, 이 컨텍스트에서는 허용되지 않는다.

`UV_CONFIG_FILE` 환경 변수로도 설정할 수 있다.
--directory directory
명령어 실행 전에 주어진 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 `--project`를 참조한다.

--help, `-h`
이 명령어에 대한 간결한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 `webpki-roots` 크레이트에서 인증서를 로드한다. `webpki-roots`는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, uv에 포함되어 이식성과 성능(특히 macOS에서)을 향상시킨다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려면 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

`UV_NATIVE_TLS` 환경 변수로도 설정할 수 있다.
--no-cache, `-n`
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

`UV_NO_CACHE` 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(`pyproject.toml`, `uv.toml`)을 발견하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리 또는 사용자 설정 디렉토리에서 발견된다.

`UV_NO_CONFIG` 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예: 스피너 또는 진행률 표시줄.

`UV_NO_PROGRESS` 환경 변수로도 설정할 수 있다.
--no-project
Python 고정이 프로젝트 또는 작업 공간과 호환되는지 검증하지 않는다.

기본적으로 프로젝트 또는 작업 공간은 현재 디렉토리 또는 상위 디렉토리에서 발견된다. 작업 공간이 발견되면 Python 고정이 작업 공간의 `requires-python` 제약 조건에 대해 검증된다.

--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화되면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

`UV_OFFLINE` 환경 변수로도 설정할 수 있다.
--project project
주어진 프로젝트 디렉토리 내에서 명령어를 실행한다.

모든 `pyproject.toml`, `uv.toml`, `.python-version` 파일은 프로젝트 루트에서 디렉토리 트리를 올라가며 발견되며, 프로젝트의 가상 환경(`.venv`)도 마찬가지이다.

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 `--directory`를 참조한다.

이 설정은 `uv pip` 인터페이스에서 사용할 때 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 결정한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

`UV_PYTHON_PREFERENCE` 환경 변수로도 설정할 수 있다.
가능한 값:


`only-managed`: 관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

`managed`: 시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

`system`: 관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

`only-system`: 시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--quiet, `-q`
어떤 출력도 표시하지 않는다.

--resolved
요청 대신 해결된 Python 인터프리터 경로를 기록한다.

동일한 인터프리터가 사용되도록 보장한다.

이 옵션은 일반적으로 `.python-version` 파일을 버전 관리에 커밋할 때 안전하지 않다.

--verbose, `-v`
상세한 출력을 사용한다.

`RUST_LOG` 환경 변수를 사용하여 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, `-V`
uv 버전을 표시한다.




### uv 파이썬 설치 디렉토리

uv 파이썬 설치 디렉토리를 표시한다.

기본적으로 파이썬 설치 파일은 uv 데이터 디렉토리인 `$XDG_DATA_HOME/uv/python` 또는 `$HOME/.local/share/uv/python`(Unix)와 `%APPDATA%\uv\data\python`(Windows)에 저장된다.

파이썬 설치 디렉토리는 `$UV_PYTHON_INSTALL_DIR`로 재정의할 수 있다.

파이썬 실행 파일이 설치된 디렉토리를 확인하려면 `--bin` 플래그를 사용한다. 파이썬 실행 파일은 프리뷰 모드가 활성화된 경우에만 설치된다.

사용법

uv python dir [OPTIONS]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소와 비교해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 보안 네트워크에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--bin
uv python이 파이썬 실행 파일을 설치할 디렉토리를 표시한다.

이 디렉토리는 프리뷰 모드가 활성화된 상태에서 파이썬을 설치할 때만 사용된다.

파이썬 실행 파일 디렉토리는 XDG 표준에 따라 결정되며, 다음 환경 변수를 우선순위에 따라 사용한다:


$UV_PYTHON_BIN_DIR

$XDG_BIN_HOME

$XDG_DATA_HOME/../bin

$HOME/.local/bin


--cache-dir cache-dir
캐시 디렉토리의 경로를 지정한다.

기본값은 macOS와 Linux에서는 `$XDG_CACHE_HOME/uv` 또는 `$HOME/.cache/uv`, Windows에서는 `%LOCALAPPDATA%\uv\cache`이다.

캐시 디렉토리의 위치를 확인하려면 `uv cache dir`을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전송될 때만 색상 출력을 활성화한다.

always:  환경과 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정 파일인 uv.toml의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함할 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령어 실행 전에 지정된 디렉토리로 이동한다.

상대 경로는 지정된 디렉토리를 기준으로 해결된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--help, -h
이 명령어에 대한 간결한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 결정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla에서 제공하는 신뢰할 수 있는 루트 인증서 집합이며, uv에 포함되면 이식성과 성능(특히 macOS에서)이 향상된다.

하지만 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우에는 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리, 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄 등이 있다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
파이썬 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
지정된 프로젝트 디렉토리 내에서 명령어를 실행한다.

모든 pyproject.toml, uv.toml, .python-version 파일은 프로젝트 루트에서 디렉토리 트리를 따라 검색되며, 프로젝트의 가상 환경(.venv)도 마찬가지이다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해결된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python-preference python-preference
uv가 관리하는 파이썬 설치와 시스템 파이썬 설치 중 어느 것을 우선할지 결정한다.

기본적으로 uv는 자체적으로 관리하는 파이썬 버전을 우선 사용한다. 하지만 uv 관리 파이썬이 설치되지 않은 경우 시스템 파이썬 설치를 사용한다. 이 옵션을 통해 시스템 파이썬 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  uv 관리 파이썬 설치만 사용한다. 시스템 파이썬 설치를 사용하지 않는다.

managed:  시스템 파이썬 설치보다 uv 관리 파이썬 설치를 우선한다.

system:  uv 관리 파이썬 설치보다 시스템 파이썬 설치를 우선한다.

only-system:  시스템 파이썬 설치만 사용한다. uv 관리 파이썬 설치를 사용하지 않는다.

--quiet, -q
출력을 표시하지 않는다.

--verbose, -v
상세 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 설정할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv python uninstall

Python 버전 제거

사용법

uv python uninstall [OPTIONS] <TARGETS>...


인자

TARGETS
제거할 Python 버전

지원되는 요청 형식은 uv python을 참고한다.



옵션

--all
관리되는 모든 Python 버전 제거

--allow-insecure-host allow-insecure-host
호스트에 대한 보안되지 않은 연결 허용

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉터리 경로

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉터리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에 색상 사용 여부 제어

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 터미널 또는 TTY로 향할 때만 색상 출력 활성화

always:  환경 감지와 관계없이 항상 색상 출력 활성화

never:  색상 출력 비활성화

--config-file config-file
설정에 사용할 uv.toml 파일 경로

uv 설정은 pyproject.toml 파일에 포함할 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령 실행 전 주어진 디렉터리로 변경

상대 경로는 주어진 디렉터리를 기준으로 해석된다.

프로젝트 루트 디렉터리만 변경하려면 --project를 참고한다.

--help, -h
이 명령에 대한 간단한 도움말 표시

--install-dir, -i install-dir
Python이 설치된 디렉터리

UV_PYTHON_INSTALL_DIR 환경 변수로도 설정할 수 있다.
--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합으로, uv에 포함되어 이식성과 성능(특히 macOS에서)을 향상시킨다.

하지만 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우, 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉터리 사용

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않음

일반적으로 설정 파일은 현재 디렉터리, 상위 디렉터리, 또는 사용자 설정 디렉터리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력 숨김

예: 스피너 또는 진행률 표시줄

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python 자동 다운로드 비활성화

--offline
네트워크 접근 비활성화

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
주어진 프로젝트 디렉터리 내에서 명령 실행

프로젝트 루트에서 시작해 디렉터리 트리를 따라 올라가면서 pyproject.toml, uv.toml, .python-version 파일을 검색한다. 프로젝트의 가상 환경(.venv)도 마찬가지다.

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉터리를 기준으로 해석된다.

작업 디렉터리를 완전히 변경하려면 --directory를 참고한다.

이 설정은 uv pip 인터페이스에서는 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 여부

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 하지만 관리되는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용; 시스템 Python 설치 사용 안 함

managed:  시스템 Python 설치보다 관리되는 Python 설치 우선

system:  관리되는 Python 설치보다 시스템 Python 설치 우선

only-system:  시스템 Python 설치만 사용; 관리되는 Python 설치 사용 안 함

--quiet, -q
출력하지 않음

--verbose, -v
상세 출력 사용

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전 표시




## uv pip

pip 호환 인터페이스로 Python 패키지 관리

사용법

uv pip [옵션] <명령어>


명령어

uv pip compile
requirements.in 파일을 requirements.txt 파일로 컴파일한다

uv pip sync
requirements.txt 파일에 맞게 환경을 동기화한다

uv pip install
환경에 패키지를 설치한다

uv pip uninstall
환경에서 패키지를 제거한다

uv pip freeze
환경에 설치된 패키지를 requirements 형식으로 나열한다

uv pip list
환경에 설치된 패키지를 표 형식으로 나열한다

uv pip show
설치된 하나 이상의 패키지에 대한 정보를 보여준다

uv pip tree
환경의 의존성 트리를 표시한다

uv pip check
설치된 패키지의 의존성이 호환되는지 확인한다




### uv pip compile

`requirements.in` 파일을 `requirements.txt` 파일로 컴파일한다.

사용법

uv pip compile [OPTIONS] <SRC_FILE>...


인자

SRC_FILE
주어진 requirements.in 파일에 나열된 모든 패키지를 포함한다.

pyproject.toml, setup.py, 또는 setup.cfg 파일이 제공되면 uv는 해당 프로젝트의 요구사항을 추출한다.

-가 제공되면 요구사항은 stdin에서 읽어온다.

요구사항 파일과 그 안의 요구사항 순서는 해결 과정에서 우선순위를 결정하는 데 사용된다.



옵션

--all-extras
모든 선택적 의존성을 포함한다.

pyproject.toml, setup.py, setup.cfg 소스에만 적용된다.

--allow-insecure-host allow-insecure-host
호스트에 대한 보안되지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 보안 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--annotation-style annotation-style
출력 파일에 포함된 주석 스타일을 지정한다. 각 패키지의 출처를 나타내는 데 사용된다.

기본값은 split이다.

가능한 값:


line: 주석을 단일 쉼표로 구분된 줄에 렌더링

split: 각 주석을 별도의 줄에 렌더링

--build-constraints, -b build-constraints
소스 배포를 빌드할 때 주어진 요구사항 파일을 사용해 빌드 의존성을 제한한다.

제약 파일은 설치되는 요구사항의 버전만 제어하는 requirements.txt와 유사한 파일이다. 그러나 제약 파일에 패키지를 포함해도 해당 패키지의 설치를 트리거하지 않는다.

UV_BUILD_CONSTRAINT 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에 색상을 사용하는 방식을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto: 출력이 색상을 지원하는 터미널 또는 TTY로 향할 때만 색상 출력 활성화

always: 환경 감지와 관계없이 항상 색상 출력 활성화

never: 색상 출력 비활성화

--config-file config-file
설정에 사용할 uv.toml 파일 경로.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정을 KEY=VALUE 쌍으로 지정

--constraints, -c constraints
주어진 요구사항 파일을 사용해 버전을 제한한다.

제약 파일은 설치되는 요구사항의 버전만 제어하는 requirements.txt와 유사한 파일이다. 그러나 제약 파일에 패키지를 포함해도 해당 패키지의 설치를 트리거하지 않는다.

이 옵션은 pip의 --constraint 옵션과 동일하다.

UV_CONSTRAINT 환경 변수로도 설정할 수 있다.
--custom-compile-command custom-compile-command
uv pip compile에 의해 생성된 출력 파일 상단에 포함할 헤더 주석.

uv pip compile을 감싸는 커스텀 빌드 스크립트와 커맨드를 반영하는 데 사용된다.

UV_CUSTOM_COMPILE_COMMAND 환경 변수로도 설정할 수 있다.
--default-index default-index
기본 패키지 인덱스 URL (기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 지정된 인덱스는 --index 플래그로 지정된 모든 다른 인덱스보다 낮은 우선순위를 가진다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--directory directory
커맨드를 실행하기 전에 주어진 디렉토리로 변경한다.

상대 경로는 주어진 디렉토리를 기준으로 해결된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--emit-build-options
생성된 출력 파일에 --no-binary 및 --only-binary 항목을 포함한다.

--emit-find-links
생성된 출력 파일에 --find-links 항목을 포함한다.

--emit-index-annotation
각 패키지를 해결하는 데 사용된 인덱스를 나타내는 주석을 포함한다 (예: # from https://pypi.org/simple).

--emit-index-url
생성된 출력 파일에 --index-url 및 --extra-index-url 항목을 포함한다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z) 및 동일한 형식의 로컬 날짜(예: 2006-12-02)를 시스템의 구성된 시간대로 받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra extra
지정된 추가 이름에서 선택적 의존성을 포함한다. 여러 번 제공할 수 있다.

pyproject.toml, setup.py, setup.cfg 소스에만 적용된다.

--extra-index-url extra-index-url
(사용 중단: --index 대신 사용) --index-url에 추가로 사용할 패키지 인덱스 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 모든 인덱스는 --index-url로 지정된 인덱스(기본값은 PyPI)보다 높은 우선순위를 가진다. 여러 --extra-index-url 플래그가 제공되면 이전 값이 우선순위를 가진다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스에서 찾은 것 외에 후보 배포를 검색할 위치.

경로인 경우, 대상은 최상위 수준에 휠 파일(.whl) 또는 소스 배포(예: .tar.gz 또는 .zip)가 포함된 디렉토리여야 한다.

URL인 경우, 페이지는 위에서 설명한 형식을 준수하는 패키지 파일에 대한 링크의 평면 목록을 포함해야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--fork-strategy fork-strategy
여러 Python 버전 및 플랫폼에서 주어진 패키지의 여러 버전을 선택할 때 사용할 전략.

기본적으로 uv는 각 지원 Python 버전(requires-python)에 대해 각 패키지의 최신 버전을 선택하는 동시에 플랫폼 간 선택된 버전 수를 최소화한다.

fewest에서는 uv는 각 패키지에 대해 선택된 버전 수를 최소화하며, 더 넓은 범위의 지원 Python 버전 또는 플랫폼과 호환되는 이전 버전을 선호한다.

UV_FORK_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


fewest: 각 패키지에 대해 선택된 버전 수를 최소화하도록 최적화. 더 넓은 범위의 지원 Python 버전 또는 플랫폼과 호환되는 경우 이전 버전 선호

requires-python: 각 지원 Python 버전에 대해 각 패키지의 최신 지원 버전을 선택하도록 최적화

--generate-hashes
출력 파일에 배포 해시를 포함한다.

--help, -h
이 커맨드에 대한 간결한 도움말을 표시한다.

--index index
기본 인덱스 외에 의존성을 해결할 때 사용할 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 모든 인덱스는 --default-index로 지정된 인덱스(기본값은 PyPI)보다 높은 우선순위를 가진다. 여러 --index 플래그가 제공되면 이전 값이 우선순위를 가진다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략.

기본적으로 uv는 주어진 패키지 이름에 대해 첫 번째 인덱스에서 사용 가능한 패키지에서 멈추고, 해당 첫 번째 인덱스에 있는 패키지로 해결을 제한한다(first-index). 이는 공격자가 동일한 이름으로 악성 패키지를 대체 인덱스에 업로드할 수 있는 "의존성 혼란" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index: 주어진 패키지 이름에 대해 첫 번째 인덱스에서 반환된 결과만 사용

unsafe-first-match: 모든 인덱스에서 모든 패키지 이름을 검색하며, 첫 번째 인덱스의 버전을 모두 소진한 후 다음 인덱스로 이동

unsafe-best-match: 모든 인덱스에서 모든 패키지 이름을 검색하며, 찾은 "최상" 버전을 선호. 패키지 버전이 여러 인덱스에 있는 경우 첫 번째 인덱스의 항목만 확인

--index-url, -i index-url
(사용 중단: --default-index 대신 사용) Python 패키지 인덱스 URL (기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 받한다.

이 플래그로 지정된 인덱스는 --extra-index-url 플래그로 지정된 모든 다른 인덱스보다 낮은 우선순위를 가진다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--keyring-provider keyring-provider
인덱스 URL에 대한 인증을 위해 keyring 사용을 시도한다.

현재 --keyring-provider subprocess만 지원되며, 이는 uv가 keyring CLI를 사용해 인증을 처리하도록 설정한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled: 자격 증명 조회를 위해 keyring 사용 안 함

subprocess: 자격 증명 조회를 위해 keyring 커맨드 사용

--link-mode link-mode
글로벌 캐시에서 패키지를 설치할 때 사용할 방법.

이 옵션은 소스 배포를 빌드할 때만 사용된다.

기본값은 macOS에서는 clone(Copy-on-Write라고도 함), Linux와 Windows에서는 hardlink이다.

UV_LINK_MODE 환경 변수로도 설정할 수 있다.
가능한 값:


clone: 휠에서 site-packages 디렉토리로 패키지를 복제(즉, Copy-on-Write)

copy: 휠에서 site-packages 디렉토리로 패키지를 복사

hardlink: 휠에서 site-packages 디렉토리로 패키지를 하드 링크

symlink: 휠에서 site-packages 디렉토리로 패키지를 심볼릭 링크

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 집합이며, uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-annotate
각 패키지의 출처를 나타내는 주석을 제외한다.

--no-binary no-binary
미리 빌드된 휠을 설치하지 않는다.

주어진 패키지는 소스에서 빌드되고 설치된다. 해결자는 여전히 사용 가능한 경우 미리 빌드된 휠을 사용해 패키지 메타데이터를 추출한다.

여러 패키지를 제공할 수 있다. 모든 패키지에 대해 바이너리를 비활성화하려면 :all:을 사용한다. 이전에 지정된 패키지를 지우려면 :none:을 사용한다.

--no-build
소스 배포를 빌드하지 않는다.

활성화되면 해결은 임의의 Python 코드를 실행하지 않는다. 이미 빌드된 소스 배포의 캐시된 휠은 재사용되지만, 배포를 빌드해야 하는 작업은 오류와 함께 종료된다.

--only-binary :all:의 별칭이다.

--no-build-isolation
소스 배포를 빌드할 때 격리를 비활성화한다.

PEP 518에 의해 지정된 빌드 의존성이 이미 설치되어 있다고 가정한다.

UV_NO_BUILD_ISOLATION 환경 변수로도 설정할 수 있다.
--no-build-isolation-package no-build-isolation-package
특정 패키지에 대해 소스 배포를 빌드할 때 격리를 비활성화한다.

패키지의 빌드 의존성이 PEP 518에 의해 이미 설치되어 있다고 가정한다.

--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-deps
패키지 의존성을 무시하고, 커맨드 라인에 명시적으로 나열된 패키지만 결과 요구사항 파일에 추가한다.

--no-emit-package no-emit-package
출력 해결에서 제외할 패키지를 지정한다. 그 의존성은 여전히 해결에 포함된다. pip-compile의 --unsafe-package 옵션과 동일하다.

--no-header
생성된 출력 파일 상단의 주석 헤더를 제외한다.

--no-index
레지스트리 인덱스(예: PyPI)를 무시하고, 직접 URL 의존성과 --find-links를 통해 제공된 의존성만 사용한다.

--no-progress
모든 진행 상황 출력을 숨긴다.

예: 스피너 또는 진행률 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--no-sources
의존성을 해결할 때 tool.uv.sources 테이블을 무시한다. 워크스페이스, Git, URL 또는 로컬 경로 소스를 사용하는 대신 표준을 준수하고 게시 가능한 패키지 메타데이터에 대해 잠그는 데 사용된다.

--no-strip-extras
출력 파일에 추가 기능을 포함한다.

기본적으로 uv는 추가 기능을 제거한다. 추가 기능에 의해 끌어온 패키지는 이미 출력 파일에 직접 의존성으로 포함되어 있기 때문이다. 또한 --no-strip-extras로 생성된 출력 파일은 install 및 sync 호출에서 제약 파일로 사용할 수 없다.

--no-strip-markers
출력 파일에 환경 마커를 포함한다.

기본적으로 uv는 환경 마커를 제거한다. compile에 의해 생성된 해결은 대상 환경에 대해서만 정확함이 보장되기 때문이다.

--offline
네트워크 접근을 비활성화한다.

비활성화되면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--only-binary only-binary
미리 빌드된 휠만 사용한다. 소스 배포를 빌드하지 않는다.

활성화되면 해결은 주어진 패키지의 코드를 실행하지 않는다. 이미 빌드된 소스 배포의 캐시된 휠은 재사용되지만, 배포를 빌드해야 하는 작업은 오류와 함께 종료된다.

여러 패키지를 제공할 수 있다. 모든 패키지에 대해 바이너리를 비활성화하려면 :all:을 사용한다. 이전에 지정된 패키지를 지우려면 :none:을 사용한다.

--output-file, -o output-file
컴파일된 요구사항을 주어진 requirements.txt 파일에 쓴다.

파일이 이미 존재하면 기존 버전이 선호되며, --upgrade도 지정되지 않는 한 의존성을 해결할 때 사용된다.

--overrides overrides
주어진 요구사항 파일을 사용해 버전을 재정의한다.

재정의 파일은 구성 패키지의 요구사항과 관계없이, 그리고 이 작업이 유효하지 않은 해결로 간주될지 여부와 관계없이 특정 버전의 요구사항을 강제로 설치하는 requirements.txt와 유사한 파일이다.

제약은 추가적이며, 구성 패키지의 요구사항과 결합된다. 반면 재정의는 절대적이며, 구성 패키지의 요구사항을 완전히 대체한다.

UV_OVERRIDE 환경 변수로도 설정할 수 있다.
--prerelease prerelease
사전 릴리스 버전을 고려할 때 사용할 전략.

기본적으로 uv는 오직 사전 릴리스만 게시하는 패키지와 선언된 지정자에 명시적 사전 릴리스 마커가 포함된 첫 번째 요구사항(if-necessary-or-explicit)에 대해 사전 릴리스를 허용한다.

UV_PRERELEASE 환경 변수로도 설정할 수 있다.
가능한 값:


disallow: 모든 사전 릴리스 버전을 허용하지 않음

allow: 모든 사전 릴리스 버전을 허용

if-necessary: 패키지의 모든 버전이 사전 릴리스인 경우 사전 릴리스 버전을 허용

explicit: 버전 요구사항에 명시적 사전 릴리스 마커가 있는 첫 번째 패키지에 대해 사전 릴리스 버전을 허용

if-necessary-or-explicit: 패키지의 모든 버전이 사전 릴리스인 경우 또는 패키지에 버전 요구사항에 명시적 사전 릴리스 마커가 있는 경우 사전 릴리스 버전을 허용

--project project
주어진 프로젝트 디렉토리 내에서 커맨드를 실행한다.

프로젝트 루트에서 디렉토리 트리를 따라 올라가면서 모든 pyproject.toml, uv.toml, .python-version 파일과 프로젝트의 가상 환경(.venv)을 발견한다.

다른 커맨드 라인 인자(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해결된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python, -p python
해결 중에 사용할 Python 인터프리터.

휠이 없는 경우 패키지 메타데이터를 결정하기 위해 소스 배포를 빌드할 때 Python 인터프리터가 필요하다.

인터프리터는 --python-version이 제공되지 않는 한 기본 최소 Python 버전을 결정하는 데도 사용된다.

이 옵션은 UV_PYTHON을 존중하지만, 환경 변수를 통해 설정된 경우 --python-version에 의해 재정의된다.

Python 발견 및 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참조한다.

--python-platform python-platform
요구사항을 해결할 플랫폼.

대상 플랫폼을 CPU, 공급자 및 운영 체제 이름으로 설명하는 "대상 삼중항" 문자열로 표현한다 (예: x86_64-unknown-linux-gnu 또는 aarch64-apple-darwin).

macOS(Darwin)를 대상으로 할 때 기본 최소 버전은 12.0이다. 다른 최소 버전을 지정하려면 MACOSX_DEPLOYMENT_TARGET을 사용한다 (예: 13.0).

가능한 값:


windows: x86_64-pc-windows-msvc의 별칭, Windows의 기본 대상

linux: x86_64-unknown-linux-gnu의 별칭, Linux의 기본 대상

macos: aarch64-apple-darwin의 별칭, macOS의 기본 대상

x86_64-pc-windows-msvc: 64비트 x86 Windows 대상

i686-pc-windows-msvc: 32비트 x86 Windows 대상

x86_64-unknown-linux-gnu: x86 Linux 대상. x86_64-manylinux_2_17과 동일

aarch64-apple-darwin: Apple Silicon 장치에서 볼 수 있는 ARM 기반 macOS 대상

x86_64-apple-darwin: x86 macOS 대상

aarch64-unknown-linux-gnu: ARM64 Linux 대상. aarch64-manylinux_2_17과 동일

aarch64-unknown-linux-musl: ARM64 Linux 대상

x86_64-unknown-linux-musl: x86_64 Linux 대상

x86_64-manylinux2014: manylinux2014 플랫폼의 x86_64 대상. x86_64-manylinux_2_17과 동일

x86_64-manylinux_2_17: manylinux_2_17 플랫폼의 x86_64 대상

x86_64-manylinux_2_28: manylinux_2_28 플랫폼의 x86_64 대상

x86_64-manylinux_2_31: manylinux_2_31 플랫폼의 x86_64 대상

x86_64-manylinux_2_32: manylinux_2_32 플랫폼의 x86_64 대상

x86_64-manylinux_2_33: manylinux_2_33 플랫폼의 x86_64 대상

x86_64-manylinux_2_34: manylinux_2_34 플랫폼의 x86_64 대상

x86_64-manylinux_2_35: manylinux_2_35 플랫폼의 x86_64 대상

x86_64-manylinux_2_36: manylinux_2_36 플랫폼의 x86_64 대상

x86_64-manylinux_2_37: manylinux_2_37 플랫폼의 x86_64 대상

x86_64-manylinux_2_38: manylinux_2_38 플랫폼의 x86_64 대상

x86_64-manylinux_2_39: manylinux_2_39 플랫폼의 x86_64 대상

x86_64-manylinux_2_40: manylinux_2_40 플랫폼의 x86_64 대상

aarch64-manylinux2014: manylinux2014 플랫폼의 ARM64 대상. aarch64-manylinux_2_17과 동일

aarch64-manylinux_2_17: manylinux_2_17 플랫폼의 ARM64 대상

aarch64-manylinux_2_28: manylinux_2_28 플랫폼의 ARM64 대상

aarch64-manylinux_2_31: manylinux_2_31 플랫폼의 ARM64 대상

aarch64-manylinux_2_32: manylinux_2_32 플랫폼의 ARM64 대상

aarch64-manylinux_2_33: manylinux_2_33 플랫폼의 ARM64 대상

aarch64-manylinux_2_34: manylinux_2_34 플랫폼의 ARM64 대상

aarch64-manylinux_2_35: manylinux_2_35 플랫폼의 ARM64 대상

aarch64-manylinux_2_36: manylinux_2_36 플랫폼의 ARM64 대상

aarch64-manylinux_2_37: manylinux_2_37 플랫폼의 ARM64 대상

aarch64-manylinux_2_38: manylinux_2_38 플랫폼의 ARM64 대상

aarch64-manylinux_2_39: manylinux_2_39 플랫폼의 ARM64 대상

aarch64-manylinux_2_40: manylinux_2_40 플랫폼의 ARM64 대상

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 선호할지 여부.

기본적으로 uv는 관리하는 Python 버전을 사용하는 것을 선호한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션은 시스템 Python 설치를 우선시하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed: 관리되는 Python 설치만 사용. 시스템 Python 설치를 사용하지 않음

managed: 관리되는 Python 설치를 시스템 Python 설치보다 우선시

system: 시스템 Python 설치를 관리되는 Python 설치보다 우선시

only-system: 시스템 Python 설치만 사용. 관리되는 Python 설치를 사용하지 않음

--python-version python-version
해결에 사용할 Python 버전.

예: 3.8 또는 3.8.17.

기본값은 해결에 사용된 Python 인터프리터의 버전이다.

해결된 요구사항이 지원해야 하는 최소 Python 버전을 정의한다.

패치 버전이 생략되면 최소 패치 버전이 가정된다. 예: 3.8은 3.8.0으로 매핑된다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--refresh
모든 캐시 데이터를 새로 고친다.

--refresh-package refresh-package
특정 패키지의 캐시 데이터를 새로 고친다.

--resolution resolution
주어진 패키지 요구사항에 대해 서로 다른 호환 버전을 선택할 때 사용할 전략.

기본적으로 uv는 각 패키지의 최신 호환 버전(highest)을 사용한다.

UV_RESOLUTION 환경 변수로도 설정할 수 있다.
가능한 값:


highest: 각 패키지의 최신 호환 버전을 해결

lowest: 각 패키지의 최소 호환 버전을 해결

lowest-direct: 직접 의존성의 최소 호환 버전을 해결하고, 전이 의존성의 최신 호환 버전을 해결

--system
패키지를 시스템 Python 환경에 설치한다.

기본적으로 uv는 현재 작업 디렉토리 또는 상위 디렉토리의 가상 환경을 사용하며, PATH에서 Python 실행 파일을 검색한다. --system 옵션은 uv가 가상 환경 Python을 사용하지 않고 시스템 경로로 검색을 제한하도록 지시한다.

UV_SYSTEM_PYTHON 환경 변수로도 설정할 수 있다.
--universal
범용 해결을 수행하여 모든 운영 체제, 아키텍처 및 Python 구현과 호환되는 단일 requirements.txt 출력 파일을 생성한다.

범용 모드에서 현재 Python 버전(또는 사용자 제공 --python-version)은 하한으로 처리된다. 예: --universal --python-version 3.7은 Python 3.7 이상에 대한 범용 해결을 생성한다.

--no-strip-markers를 암시한다.

--upgrade, -U
패키지 업그레이드를 허용하고 기존 출력 파일의 고정 버전을 무시한다. --refresh를 암시한다.

--upgrade-package, -P upgrade-package
특정 패키지의 업그레이드를 허용하고 기존 출력 파일의 고정 버전을 무시한다. --refresh-package를 암시한다.

--verbose, -v
자세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv pip sync

`requirements.txt` 파일과 환경을 동기화한다.

사용법

uv pip sync [OPTIONS] <SRC_FILE>...


인자

SRC_FILE
주어진 requirements.txt 파일에 나열된 모든 패키지를 포함한다.

pyproject.toml, setup.py, 또는 setup.cfg 파일이 제공되면, uv는 해당 프로젝트의 요구 사항을 추출한다.

-가 제공되면, 요구 사항은 stdin에서 읽어온다.



옵션

--allow-empty-requirements
빈 요구 사항의 동기화를 허용한다. 이 경우 환경의 모든 패키지를 제거한다.

--allow-insecure-host allow-insecure-host
호스트에 대한 안전하지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크와 소스에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--break-system-packages
uv가 EXTERNALLY-MANAGED Python 설치를 수정하도록 허용한다.

경고: --break-system-packages는 외부 패키지 관리자(예: apt)가 관리하는 Python 설치에 패키지를 설치할 때, 주로 CI 환경에서 사용한다. uv나 pip와 같은 다른 패키지 관리자에 의한 수정을 명시적으로 권장하지 않는 Python 설치에서 사용 시 주의가 필요하다.

UV_BREAK_SYSTEM_PACKAGES 환경 변수로도 설정할 수 있다.
--build-constraints, -b build-constraints
소스 배포를 빌드할 때 주어진 요구 사항 파일을 사용해 빌드 종속성을 제한한다.

제약 파일은 requirements.txt와 유사하지만, 설치되는 요구 사항의 버전만 제어한다. 제약 파일에 패키지를 포함해도 해당 패키지가 설치되지는 않는다.

UV_BUILD_CONSTRAINT 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전달될 때만 색상 출력을 활성화한다.

always:  환경과 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--compile-bytecode
설치 후 Python 파일을 바이트코드로 컴파일한다.

기본적으로 uv는 Python(.py) 파일을 바이트코드(__pycache__/*.pyc)로 컴파일하지 않는다. 대신 모듈을 처음 임포트할 때 지연 컴파일을 수행한다. CLI 애플리케이션이나 Docker 컨테이너와 같이 시작 시간이 중요한 경우, 이 옵션을 활성화해 설치 시간을 늘리는 대신 시작 시간을 단축할 수 있다.

활성화되면, uv는 전체 site-packages 디렉토리(현재 작업으로 수정되지 않는 패키지 포함)를 일관성 있게 처리한다. pip와 마찬가지로 오류는 무시한다.

UV_COMPILE_BYTECODE 환경 변수로도 설정할 수 있다.
--config-file config-file
설정에 사용할 uv.toml 파일 경로.

uv 설정은 pyproject.toml 파일에 포함할 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정을 KEY=VALUE 쌍으로 지정한다.

--constraints, -c constraints
주어진 요구 사항 파일을 사용해 버전을 제한한다.

제약 파일은 requirements.txt와 유사하지만, 설치되는 요구 사항의 버전만 제어한다. 제약 파일에 패키지를 포함해도 해당 패키지가 설치되지는 않는다.

이는 pip의 --constraint 옵션과 동일하다.

UV_CONSTRAINT 환경 변수로도 설정할 수 있다.
--default-index default-index
기본 패키지 인덱스 URL (기본값: <https://pypi.org/simple>).

PEP 503을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 인덱스는 --index 플래그로 지정된 모든 인덱스보다 낮은 우선순위를 가진다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 주어진 디렉토리로 변경한다.

상대 경로는 주어진 디렉토리를 기준으로 해결된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참고한다.

--dry-run
드라이 런을 수행한다. 실제로는 아무것도 설치하지 않고 종속성을 해결한 후 결과 계획을 출력한다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z) 또는 시스템의 시간대에 따른 동일 형식의 로컬 날짜(예: 2006-12-02)를 받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra-index-url extra-index-url
(사용 중단: --index를 대신 사용) --index-url 외에 사용할 추가 패키지 인덱스 URL.

PEP 503을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 모든 인덱스는 --index-url로 지정된 인덱스(기본값: PyPI)보다 높은 우선순위를 가진다. 여러 --extra-index-url 플래그가 제공되면, 먼저 제공된 값이 더 높은 우선순위를 가진다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스 외에 후보 배포를 검색할 위치.

경로인 경우, 대상은 최상위에 휠 파일(.whl) 또는 소스 배포(예: .tar.gz 또는 .zip)가 포함된 디렉토리여야 한다.

URL인 경우, 페이지는 위에서 설명한 형식의 패키지 파일에 대한 링크의 단순 목록을 포함해야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--help, -h
이 명령에 대한 간단한 도움말을 표시한다.

--index index
기본 인덱스 외에 종속성을 해결할 때 사용할 URL.

PEP 503을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 모든 인덱스는 --default-index로 지정된 인덱스(기본값: PyPI)보다 높은 우선순위를 가진다. 여러 --index 플래그가 제공되면, 먼저 제공된 값이 더 높은 우선순위를 가진다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략.

기본적으로 uv는 주어진 패키지가 사용 가능한 첫 번째 인덱스에서 멈추고, 해결을 해당 첫 번째 인덱스에 있는 것으로 제한한다(first-index). 이는 공격자가 대체 인덱스에 동일한 이름의 악성 패키지를 업로드할 수 있는 "의존성 혼란" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  주어진 패키지 이름에 대해 첫 번째로 일치하는 인덱스의 결과만 사용한다.

unsafe-first-match:  모든 패키지 이름에 대해 모든 인덱스를 검색하며, 첫 번째 인덱스의 버전을 모두 소진한 후 다음 인덱스로 이동한다.

unsafe-best-match:  모든 패키지 이름에 대해 모든 인덱스를 검색하며, "최상의" 버전을 선호한다. 패키지 버전이 여러 인덱스에 있는 경우, 첫 번째 인덱스의 항목만 확인한다.

--index-url, -i index-url
(사용 중단: --default-index를 대신 사용) Python 패키지 인덱스 URL (기본값: <https://pypi.org/simple>).

PEP 503을 준수하는 저장소 또는 동일한 형식의 로컬 디렉토리를 받는다.

이 플래그로 제공된 인덱스는 --extra-index-url 플래그로 지정된 모든 인덱스보다 낮은 우선순위를 가진다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--keyring-provider keyring-provider
인덱스 URL에 대해 keyring을 사용해 인증을 시도한다.

현재는 --keyring-provider subprocess만 지원하며, 이는 uv가 keyring CLI를 사용해 인증을 처리하도록 설정한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회에 keyring을 사용하지 않는다.

subprocess:  keyring 명령을 사용해 자격 증명을 조회한다.

--link-mode link-mode
글로벌 캐시에서 패키지를 설치할 때 사용할 방법.

기본값은 macOS에서는 clone(Copy-on-Write), Linux와 Windows에서는 hardlink이다.

UV_LINK_MODE 환경 변수로도 설정할 수 있다.
가능한 값:


clone:  휠에서 site-packages 디렉토리로 패키지를 복제한다(즉, Copy-on-Write).

copy:  휠에서 site-packages 디렉토리로 패키지를 복사한다.

hardlink:  휠에서 site-packages 디렉토리로 패키지를 하드 링크한다.

symlink:  휠에서 site-packages 디렉토리로 패키지를 심볼릭 링크한다.

--native-tls
플랫폼의 네이티브 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 집합으로, uv에 포함되어 이식성과 성능(특히 macOS에서)을 향상시킨다.

하지만 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 기업 신뢰 루트(예: 필수 프록시)를 사용할 때는 플랫폼의 네이티브 인증서 저장소를 사용하고 싶을 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-allow-empty-requirements
--no-binary no-binary
미리 빌드된 휠을 설치하지 않는다.

주어진 패키지는 소스에서 빌드되어 설치된다. 리졸버는 여전히 사용 가능한 경우 미리 빌드된 휠을 사용해 패키지 메타데이터를 추출한다.

여러 패키지를 제공할 수 있다. 모든 패키지에 대해 바이너리를 비활성화하려면 :all:을 사용한다. 이전에 지정한 패키지를 지우려면 :none:을 사용한다.

--no-break-system-packages
--no-build
소스 배포를 빌드하지 않는다.

활성화되면, 임의의 Python 코드를 실행하지 않는다. 이미 빌드된 소스 배포의 캐시된 휠은 재사용되지만, 배포를 빌드해야 하는 작업은 오류와 함께 종료된다.

--only-binary :all:의 별칭이다.

--no-build-isolation
소스 배포를 빌드할 때 격리를 비활성화한다.

PEP 518에 의해 지정된 빌드 종속성이 이미 설치되어 있다고 가정한다.

UV_NO_BUILD_ISOLATION 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-index
레지스트리 인덱스(예: PyPI)를 무시하고, 직접 URL 종속성과 --find-links로 제공된 종속성만 사용한다.

--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--no-sources
종속성을 해결할 때 tool.uv.sources 테이블을 무시한다. 워크스페이스, Git, URL 또는 로컬 경로 소스 대신 표준 준수, 게시 가능한 패키지 메타데이터에 대해 잠금을 설정할 때 사용한다.

--no-verify-hashes
요구 사항 파일의 해시 검증을 비활성화한다.

기본적으로 uv는 요구 사항 파일에 사용 가능한 해시를 검증하지만, 모든 요구 사항이 해시를 포함할 필요는 없다. 해시 검증을 강제하려면 --require-hashes를 사용한다.

UV_NO_VERIFY_HASHES 환경 변수로도 설정할 수 있다.
--offline
네트워크 액세스를 비활성화한다.

비활성화되면, uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--only-binary only-binary
미리 빌드된 휠만 사용한다. 소스 배포를 빌드하지 않는다.

활성화되면, 주어진 패키지에서 코드를 실행하지 않는다. 이미 빌드된 소스 배포의 캐시된 휠은 재사용되지만, 배포를 빌드해야 하는 작업은 오류와 함께 종료된다.

여러 패키지를 제공할 수 있다. 모든 패키지에 대해 바이너리를 비활성화하려면 :all:을 사용한다. 이전에 지정한 패키지를 지우려면 :none:을 사용한다.

--prefix prefix
패키지를 지정된 디렉토리 아래의 lib, bin 및 기타 최상위 폴더에 설치한다. 마치 해당 위치에 가상 환경이 있는 것처럼.

일반적으로, 대체 환경에 설치할 때는 --python 사용을 권장한다. --prefix를 통해 설치된 스크립트 및 기타 아티팩트는 --prefix 디렉토리에 추가된 인터프리터가 아닌 설치 중인 인터프리터를 참조하므로 이식성이 떨어진다.

--project project
주어진 프로젝트 디렉토리 내에서 명령을 실행한다.

프로젝트 루트에서 디렉토리 트리를 올라가며 모든 pyproject.toml, uv.toml, 및 .python-version 파일을 찾는다. 프로젝트의 가상 환경(.venv)도 마찬가지로 발견된다.

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해결된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참고한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python, -p python
패키지를 설치할 Python 인터프리터.

기본적으로, 동기화는 가상 환경을 필요로 한다. 대체 Python 경로를 제공할 수 있지만, 주로 CI 환경에서 권장되며 시스템 Python 설치를 수정할 수 있으므로 주의해서 사용한다.

Python 탐색 및 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참고한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-platform python-platform
요구 사항을 설치할 플랫폼.

"target triple"로 표현되며, CPU, 벤더, 운영 체제 이름을 설명하는 문자열이다(예: x86_64-unknown-linux-gnu 또는 aarch64-apple-darwin).

macOS(Darwin)를 대상으로 할 때, 기본 최소 버전은 12.0이다. 다른 최소 버전을 지정하려면 MACOSX_DEPLOYMENT_TARGET을 사용한다(예: 13.0).

경고: 지정된 경우, uv는 대상 플랫폼과 호환되는 휠을 선택한다. 결과적으로 설치된 배포가 현재 플랫폼과 호환되지 않을 수 있다. 반대로, 소스에서 빌드된 배포는 현재 플랫폼용으로 빌드되므로 대상 플랫폼과 호환되지 않을 수 있다. --python-platform 옵션은 고급 사용 사례를 위한 것이다.

가능한 값:


windows:  x86_64-pc-windows-msvc의 별칭, Windows의 기본 대상.

linux:  x86_64-unknown-linux-gnu의 별칭, Linux의 기본 대상.

macos:  aarch64-apple-darwin의 별칭, macOS의 기본 대상.

x86_64-pc-windows-msvc:  64비트 x86 Windows 대상.

i686-pc-windows-msvc:  32비트 x86 Windows 대상.

x86_64-unknown-linux-gnu:  x86 Linux 대상. x86_64-manylinux_2_17과 동일.

aarch64-apple-darwin:  Apple Silicon 장치에서 볼 수 있는 ARM 기반 macOS 대상.

x86_64-apple-darwin:  x86 macOS 대상.

aarch64-unknown-linux-gnu:  ARM64 Linux 대상. aarch64-manylinux_2_17과 동일.

aarch64-unknown-linux-musl:  ARM64 Linux 대상.

x86_64-unknown-linux-musl:  x86_64 Linux 대상.

x86_64-manylinux2014:  manylinux2014 플랫폼의 x86_64 대상. x86_64-manylinux_2_17과 동일.

x86_64-manylinux_2_17:  manylinux_2_17 플랫폼의 x86_64 대상.

x86_64-manylinux_2_28:  manylinux_2_28 플랫폼의 x86_64 대상.

x86_64-manylinux_2_31:  manylinux_2_31 플랫폼의 x86_64 대상.

x86_64-manylinux_2_32:  manylinux_2_32 플랫폼의 x86_64 대상.

x86_64-manylinux_2_33:  manylinux_2_33 플랫폼의 x86_64 대상.

x86_64-manylinux_2_34:  manylinux_2_34 플랫폼의 x86_64 대상.

x86_64-manylinux_2_35:  manylinux_2_35 플랫폼의 x86_64 대상.

x86_64-manylinux_2_36:  manylinux_2_36 플랫폼의 x86_64 대상.

x86_64-manylinux_2_37:  manylinux_2_37 플랫폼의 x86_64 대상.

x86_64-manylinux_2_38:  manylinux_2_38 플랫폼의 x86_64 대상.

x86_64-manylinux_2_39:  manylinux_2_39 플랫폼의 x86_64 대상.

x86_64-manylinux_2_40:  manylinux_2_40 플랫폼의 x86_64 대상.

aarch64-manylinux2014:  manylinux2014 플랫폼의 ARM64 대상. aarch64-manylinux_2_17과 동일.

aarch64-manylinux_2_17:  manylinux_2_17 플랫폼의 ARM64 대상.

aarch64-manylinux_2_28:  manylinux_2_28 플랫폼의 ARM64 대상.

aarch64-manylinux_2_31:  manylinux_2_31 플랫폼의 ARM64 대상.

aarch64-manylinux_2_32:  manylinux_2_32 플랫폼의 ARM64 대상.

aarch64-manylinux_2_33:  manylinux_2_33 플랫폼의 ARM64 대상.

aarch64-manylinux_2_34:  manylinux_2_34 플랫폼의 ARM64 대상.

aarch64-manylinux_2_35:  manylinux_2_35 플랫폼의 ARM64 대상.

aarch64-manylinux_2_36:  manylinux_2_36 플랫폼의 ARM64 대상.

aarch64-manylinux_2_37:  manylinux_2_37 플랫폼의 ARM64 대상.

aarch64-manylinux_2_38:  manylinux_2_38 플랫폼의 ARM64 대상.

aarch64-manylinux_2_39:  manylinux_2_39 플랫폼의 ARM64 대상.

aarch64-manylinux_2_40:  manylinux_2_40 플랫폼의 ARM64 대상.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 하지만 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션은 시스템 Python 설치를 우선하거나 무시할 수 있게 한다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system:  시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--python-version python-version
요구 사항이 지원해야 하는 최소 Python 버전(예: 3.7 또는 3.7.9).

패치 버전이 생략된 경우, 최소 패치 버전이 가정된다. 예를 들어, 3.7은 3.7.0으로 매핑된다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--refresh
모든 캐시 데이터를 새로 고친다.

--refresh-package refresh-package
특정 패키지의 캐시 데이터를 새로 고친다.

--reinstall
이미 설치된 패키지와 관계없이 모든 패키지를 재설치한다. --refresh를 암시한다.

--reinstall-package reinstall-package
이미 설치된 패키지와 관계없이 특정 패키지를 재설치한다. --refresh-package를 암시한다.

--require-hashes
각 요구 사항에 대해 일치하는 해시를 요구한다.

기본적으로 uv는 요구 사항 파일에 사용 가능한 해시를 검증하지만, 모든 요구 사항이 해시를 포함할 필요는 없다.

--require-hashes가 활성화되면, 모든 요구 사항은 해시 또는 해시 집합을 포함해야 하며, 모든 요구 사항은 정확한 버전으로 고정(예: ==1.0.0)되거나 직접 URL로 지정되어야 한다.

해시 검증 모드는 다음과 같은 추가 제약을 도입한다:


Git 종속성은 지원되지 않는다. - 편집 가능한 설치(editable installs)는 지원되지 않는다. - 로컬 종속성은 디렉토리가 아닌 특정 휠(.whl) 또는 소스 아카이브(.zip, .tar.gz)를 가리키는 경우에만 지원된다.


UV_REQUIRE_HASHES 환경 변수로도 설정할 수 있다.
--strict
설치 완료 후 Python 환경을 검증하여 누락된 종속성 또는 기타 문제가 있는 패키지를 감지한다.

--system
시스템 Python 환경에 패키지를 설치한다.

기본적으로 uv는 현재 작업 디렉토리 또는 상위 디렉토리의 가상 환경에 설치한다. --system 옵션은 uv가 대신 시스템 PATH에서 찾은 첫 번째 Python을 사용하도록 지시한다.

경고: --system은 주로 CI 환경에서 사용되며, 시스템 Python 설치를 수정할 수 있으므로 주의해서 사용한다.

UV_SYSTEM_PYTHON 환경 변수로도 설정할 수 있다.
--target target
패키지를 가상 또는 시스템 Python 환경 대신 지정된 디렉토리에 설치한다. 패키지는 디렉토리의 최상위에 설치된다.

--verbose, -v
자세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv pip install

환경에 패키지 설치

사용법

uv pip install [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>|--editable <EDITABLE>>


인자

PACKAGE
나열된 모든 패키지를 설치한다.

패키지의 순서는 해결 과정에서 우선순위를 결정하는 데 사용된다.



옵션

--all-extras
모든 선택적 의존성을 포함한다.

pyproject.toml, setup.py, setup.cfg 소스에만 적용된다.

--allow-insecure-host allow-insecure-host
호스트에 대한 안전하지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 안전한 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--break-system-packages
uv가 EXTERNALLY-MANAGED Python 설치를 수정하도록 허용한다.

경고: --break-system-packages는 apt와 같은 외부 패키지 관리자가 관리하는 Python 설치에 패키지를 설치할 때, 지속적 통합(CI) 환경에서 사용하기 위한 것이다. uv나 pip와 같은 다른 패키지 관리자가 수정하는 것을 명시적으로 권장하지 않는 Python 설치이므로 주의해서 사용해야 한다.

UV_BREAK_SYSTEM_PACKAGES 환경 변수로도 설정할 수 있다.
--build-constraints, -b build-constraints
소스 배포를 빌드할 때 주어진 요구 사항 파일을 사용하여 빌드 의존성을 제한한다.

제약 파일은 requirements.txt와 유사한 파일로, 설치되는 요구 사항의 버전만 제어한다. 그러나 제약 파일에 패키지를 포함해도 해당 패키지의 설치를 트리거하지는 않는다.

UV_BUILD_CONSTRAINT 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 지원되는 터미널 또는 TTY로 전송될 때만 색상 출력을 활성화한다.

always:  감지된 환경과 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--compile-bytecode
설치 후 Python 파일을 바이트코드로 컴파일한다.

기본적으로 uv는 Python(.py) 파일을 바이트코드(__pycache__/*.pyc)로 컴파일하지 않는다. 대신 모듈을 처음 임포트할 때 지연 컴파일을 수행한다. CLI 애플리케이션 및 Docker 컨테이너와 같이 시작 시간이 중요한 사용 사례에서는 이 옵션을 활성화하여 더 긴 설치 시간을 감수하고 더 빠른 시작 시간을 얻을 수 있다.

활성화되면 uv는 현재 작업으로 수정되지 않은 패키지를 포함하여 전체 site-packages 디렉토리를 처리한다. pip와 마찬가지로 오류도 무시한다.

UV_COMPILE_BYTECODE 환경 변수로도 설정할 수 있다.
--config-file config-file
구성을 위해 사용할 uv.toml 파일의 경로.

uv 구성은 pyproject.toml 파일에 포함될 수 있지만, 이 컨텍스트에서는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정을 KEY=VALUE 쌍으로 지정한다.

--constraints, -c constraints
주어진 요구 사항 파일을 사용하여 버전을 제한한다.

제약 파일은 requirements.txt와 유사한 파일로, 설치되는 요구 사항의 버전만 제어한다. 그러나 제약 파일에 패키지를 포함해도 해당 패키지의 설치를 트리거하지는 않는다.

이 옵션은 pip의 --constraint 옵션과 동일하다.

UV_CONSTRAINT 환경 변수로도 설정할 수 있다.
--default-index default-index
기본 패키지 인덱스의 URL(기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식으로 구성된 로컬 디렉토리를 받는다.

이 플래그로 지정된 인덱스는 --index 플래그를 통해 지정된 다른 모든 인덱스보다 낮은 우선순위를 가진다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 주어진 디렉토리로 변경한다.

상대 경로는 주어진 디렉토리를 기준으로 해결된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--dry-run
드라이 런을 수행한다. 즉, 실제로 아무것도 설치하지 않고 의존성을 해결하고 결과 계획을 출력한다.

--editable, -e editable
제공된 로컬 파일 경로를 기반으로 편집 가능한 패키지를 설치한다.

--exact
정확한 동기화를 수행하여 불필요한 패키지를 제거한다.

기본적으로 설치 시 요구 사항을 충족하기 위한 최소한의 변경만 수행한다. 이 옵션을 활성화하면 uv는 요구 사항과 정확히 일치하도록 환경을 업데이트하고, 요구 사항에 포함되지 않은 패키지를 제거한다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z) 및 시스템의 구성된 시간대에서 동일한 형식의 로컬 날짜(예: 2006-12-02)를 받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra extra
지정된 추가 이름에서 선택적 의존성을 포함한다. 여러 번 제공할 수 있다.

pyproject.toml, setup.py, setup.cfg 소스에만 적용된다.

--extra-index-url extra-index-url
(더 이상 사용되지 않음: --index를 대신 사용) --index-url에 추가로 사용할 패키지 인덱스의 추가 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식으로 구성된 로컬 디렉토리를 받는다.

이 플래그를 통해 제공된 모든 인덱스는 --index-url로 지정된 인덱스(기본값은 PyPI)보다 높은 우선순위를 가진다. 여러 --extra-index-url 플래그가 제공되면 이전 값이 더 높은 우선순위를 가진다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스에서 찾은 것 외에 후보 배포를 검색할 위치.

경로인 경우 대상은 최상위에 휠 파일(.whl) 또는 소스 배포(예: .tar.gz 또는 .zip)가 포함된 디렉토리여야 한다.

URL인 경우 페이지는 위에서 설명한 형식을 준수하는 패키지 파일에 대한 링크의 평면 목록을 포함해야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--fork-strategy fork-strategy
여러 Python 버전 및 플랫폼에서 주어진 패키지의 여러 버전을 선택할 때 사용할 전략.

기본적으로 uv는 지원되는 각 Python 버전(requires-python)에 대해 각 패키지의 최신 버전을 선택하는 것을 최적화하면서, 플랫폼 간 선택된 버전의 수를 최소화한다.

fewest에서는 uv는 각 패키지에 대해 선택된 버전의 수를 최소화하고, 더 넓은 범위의 지원되는 Python 버전 또는 플랫폼과 호환되는 이전 버전을 선호한다.

UV_FORK_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


fewest:  각 패키지에 대해 선택된 버전의 수를 최소화하는 것을 최적화한다. 더 넓은 범위의 지원되는 Python 버전 또는 플랫폼과 호환되는 이전 버전을 선호한다.

requires-python:  지원되는 각 Python 버전에 대해 각 패키지의 최신 지원 버전을 선택하는 것을 최적화한다.

--help, -h
이 명령에 대한 간결한 도움말을 표시한다.

--index index
기본 인덱스에 추가로 의존성을 해결할 때 사용할 URL.

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식으로 구성된 로컬 디렉토리를 받는다.

이 플래그를 통해 제공된 모든 인덱스는 --default-index로 지정된 인덱스(기본값은 PyPI)보다 높은 우선순위를 가진다. 여러 --index 플래그가 제공되면 이전 값이 더 높은 우선순위를 가진다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략.

기본적으로 uv는 주어진 패키지가 사용 가능한 첫 번째 인덱스에서 중단하고, 첫 번째 인덱스에 있는 결과로만 해결을 제한한다(first-index). 이는 공격자가 대체 인덱스에 동일한 이름으로 악성 패키지를 업로드할 수 있는 "의존성 혼란" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  주어진 패키지 이름에 대해 일치하는 첫 번째 인덱스의 결과만 사용한다.

unsafe-first-match:  모든 인덱스에서 모든 패키지 이름을 검색하고, 첫 번째 인덱스의 버전을 모두 소진한 후 다음 인덱스로 이동한다.

unsafe-best-match:  모든 인덱스에서 모든 패키지 이름을 검색하고, "가장 좋은" 버전을 선호한다. 패키지 버전이 여러 인덱스에 있는 경우 첫 번째 인덱스의 항목만 확인한다.

--index-url, -i index-url
(더 이상 사용되지 않음: --default-index를 대신 사용) Python 패키지 인덱스의 URL(기본값: <https://pypi.org/simple>).

PEP 503(단순 저장소 API)을 준수하는 저장소 또는 동일한 형식으로 구성된 로컬 디렉토리를 받는다.

이 플래그로 지정된 인덱스는 --extra-index-url 플래그를 통해 지정된 다른 모든 인덱스보다 낮은 우선순위를 가진다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--keyring-provider keyring-provider
인덱스 URL에 대한 인증을 위해 keyring 사용을 시도한다.

현재 --keyring-provider subprocess만 지원되며, 이는 uv가 keyring CLI를 사용하여 인증을 처리하도록 구성한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회를 위해 keyring을 사용하지 않는다.

subprocess:  자격 증명 조회를 위해 keyring 명령을 사용한다.

--link-mode link-mode
글로벌 캐시에서 패키지를 설치할 때 사용할 방법.

기본값은 macOS에서는 clone(Copy-on-Write라고도 함), Linux와 Windows에서는 hardlink이다.

UV_LINK_MODE 환경 변수로도 설정할


### uv pip uninstall

환경에서 패키지를 제거한다.

사용법

uv pip uninstall [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>>


인자

PACKAGE
나열된 모든 패키지를 제거한다.



옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 안전하지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 소스가 있는 안전한 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--break-system-packages
uv가 EXTERNALLY-MANAGED Python 설치를 수정할 수 있도록 허용한다.

경고: --break-system-packages는 apt와 같은 외부 패키지 관리자가 관리하는 Python 설치에서 사용하기 위해 지속적 통합(CI) 환경에서 사용한다. uv나 pip와 같은 다른 패키지 관리자가 이러한 Python 설치를 수정하는 것을 명시적으로 권장하지 않으므로 주의해서 사용한다.

UV_BREAK_SYSTEM_PACKAGES 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉터리의 경로를 지정한다.

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉터리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전송될 때만 색상 출력을 활성화한다.

always:  감지된 환경에 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
구성을 위해 사용할 uv.toml 파일의 경로를 지정한다.

uv 구성은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 주어진 디렉터리로 이동한다.

상대 경로는 주어진 디렉터리를 기준으로 해석된다.

프로젝트 루트 디렉터리만 변경하려면 --project를 참조한다.

--dry-run
실제로 제거하지 않고 결과 계획을 출력하는 드라이 런을 수행한다.

--help, -h
이 명령에 대한 간결한 도움말을 표시한다.

--keyring-provider keyring-provider
원격 요구 사항 파일에 대한 인증을 위해 keyring을 사용하려고 시도한다.

현재는 --keyring-provider subprocess만 지원하며, 이는 uv가 keyring CLI를 사용하여 인증을 처리하도록 설정한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회에 keyring을 사용하지 않는다.

subprocess:  자격 증명 조회에 keyring 명령을 사용한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, 이를 uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

하지만 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)에 의존하는 경우 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-break-system-packages
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉터리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
구성 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 구성 파일은 현재 디렉터리, 상위 디렉터리, 또는 사용자 구성 디렉터리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 막대가 포함된다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--prefix prefix
지정된 --prefix 디렉터리에서 패키지를 제거한다.

--project project
주어진 프로젝트 디렉터리 내에서 명령을 실행한다.

프로젝트 루트에서 디렉터리 트리를 따라 올라가면서 pyproject.toml, uv.toml, .python-version 파일을 검색한다. 프로젝트의 가상 환경(.venv)도 검색된다.

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉터리를 기준으로 해석된다.

작업 디렉터리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python, -p python
패키지를 제거할 Python 인터프리터를 지정한다.

기본적으로 제거 작업에는 가상 환경이 필요하다. 대체 Python의 경로를 제공할 수 있지만, 이는 지속적 통합(CI) 환경에서만 권장되며 주의해서 사용해야 한다. 시스템 Python 설치를 수정할 수 있다.

Python 검색 및 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참조한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 지정한다.

기본적으로 uv는 관리하는 Python 버전을 우선적으로 사용한다. 하지만 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 사용하면 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system:  시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--requirements, -r requirements
주어진 요구 사항 파일에 나열된 모든 패키지를 제거한다.

--system
시스템 Python을 사용하여 패키지를 제거한다.

기본적으로 uv는 현재 작업 디렉터리나 상위 디렉터리의 가상 환경에서 패키지를 제거한다. --system 옵션은 uv가 시스템 PATH에서 찾은 첫 번째 Python을 사용하도록 지시한다.

경고: --system은 지속적 통합(CI) 환경에서 사용하기 위한 것이며, 시스템 Python 설치를 수정할 수 있으므로 주의해서 사용한다.

UV_SYSTEM_PYTHON 환경 변수로도 설정할 수 있다.
--target target
지정된 --target 디렉터리에서 패키지를 제거한다.

--verbose, -v
자세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용하여 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv pip freeze

환경에 설치된 패키지를 requirements 형식으로 나열한다.

사용법

uv pip freeze [OPTIONS]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 보안되지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크와 출처에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로를 지정한다.

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에 색상을 사용할지 여부를 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전달될 때만 색상 출력을 활성화한다.

always:  환경과 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정에 사용할 uv.toml 파일의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함할 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령어를 실행하기 전에 지정된 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참고한다.

--exclude-editable
출력에서 편집 가능한 패키지를 제외한다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla에서 제공하는 신뢰할 수 있는 루트 인증서 집합으로, uv에 포함되어 이식성과 성능(특히 macOS에서)을 향상시킨다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우, 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 탐색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리, 또는 사용자 설정 디렉토리에서 탐색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄 등이 있다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--path paths
패키지를 나열할 설치 경로를 지정한다(여러 번 사용 가능).

--project project
지정된 프로젝트 디렉토리 내에서 명령어를 실행한다.

모든 pyproject.toml, uv.toml, .python-version 파일은 프로젝트 루트에서 디렉토리 트리를 탐색하여 발견되며, 프로젝트의 가상 환경(.venv)도 마찬가지이다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참고한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python, -p python
패키지를 나열할 Python 인터프리터를 지정한다.

기본적으로 uv는 가상 환경의 패키지를 나열하지만, 가상 환경이 발견되지 않으면 시스템 Python 환경의 패키지를 표시한다.

Python 탐색과 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참고한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 지정한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system:  시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--strict
Python 환경을 검증하여, 누락된 종속성이 있는 패키지와 기타 문제를 감지한다.

--system
시스템 Python 환경의 패키지를 나열한다.

가상 환경 탐색을 비활성화한다.

Python 탐색에 대한 자세한 내용은 uv python을 참고한다.

UV_SYSTEM_PYTHON 환경 변수로도 설정할 수 있다.
--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용하여 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv pip list

환경에 설치된 패키지를 테이블 형식으로 나열한다.

사용법

uv pip list [OPTIONS]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 안전하지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하므로 MITM 공격에 노출될 수 있다. 신뢰할 수 있는 네트워크와 출처에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로를 지정한다.

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  터미널 또는 TTY에 출력할 때만 색상 출력을 활성화한다.

always:  환경과 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정에 사용할 uv.toml 파일의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함할 수 있지만, 이 컨텍스트에서는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--default-index default-index
기본 패키지 인덱스의 URL을 지정한다(기본값: <https://pypi.org/simple>).

PEP 503을 준수하는 저장소(단순 저장소 API) 또는 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 지정된 인덱스는 --index 플래그로 지정된 모든 인덱스보다 낮은 우선순위를 가진다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 지정된 디렉토리로 이동한다.

상대 경로는 지정된 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--editable, -e
편집 가능한 프로젝트만 포함한다.

--exclude exclude
출력에서 지정된 패키지를 제외한다.

--exclude-editable
출력에서 편집 가능한 패키지를 제외한다.

--exclude-newer exclude-newer
지정된 날짜 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z) 또는 시스템의 시간대에 맞는 로컬 날짜(예: 2006-12-02)를 입력받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra-index-url extra-index-url
(사용 중단: --index 대신 사용) --index-url에 추가로 사용할 패키지 인덱스의 URL을 지정한다.

PEP 503을 준수하는 저장소(단순 저장소 API) 또는 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 제공된 모든 인덱스는 --index-url로 지정된 인덱스(기본값: PyPI)보다 높은 우선순위를 가진다. 여러 --extra-index-url 플래그를 제공하면 이전 값이 우선순위를 가진다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스에서 찾은 것 외에 후보 배포판을 검색할 위치를 지정한다.

경로를 지정하면 대상은 최상위에 휠 파일(.whl) 또는 소스 배포판(예: .tar.gz 또는 .zip)이 포함된 디렉토리여야 한다.

URL을 지정하면 위에서 설명한 형식의 패키지 파일에 대한 링크가 포함된 평면 목록이 있어야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--format format
출력 형식을 선택한다.

[기본값: columns]
가능한 값:


columns:  패키지 목록을 사람이 읽기 쉬운 테이블로 표시한다.

freeze:  패키지 목록을 pip freeze 형식으로 표시하며, 한 줄에 하나의 패키지와 버전을 나열한다.

json:  패키지 목록을 기계가 읽을 수 있는 JSON 형식으로 표시한다.

--help, -h
이 명령에 대한 간단한 도움말을 표시한다.

--index index
의존성을 해결할 때 사용할 URL을 지정하며, 기본 인덱스에 추가로 사용한다.

PEP 503을 준수하는 저장소(단순 저장소 API) 또는 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 제공된 모든 인덱스는 --default-index로 지정된 인덱스(기본값: PyPI)보다 높은 우선순위를 가진다. 여러 --index 플래그를 제공하면 이전 값이 우선순위를 가진다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략을 지정한다.

기본적으로 uv는 주어진 패키지가 사용 가능한 첫 번째 인덱스에서 중단하고, 해당 첫 번째 인덱스에 있는 것으로 해결을 제한한다(first-index). 이는 공격자가 동일한 이름의 악성 패키지를 대체 인덱스에 업로드할 수 있는 "의존성 혼동" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  주어진 패키지 이름에 대해 첫 번째로 일치하는 인덱스의 결과만 사용한다.

unsafe-first-match:  모든 인덱스에서 패키지 이름을 검색하며, 첫 번째 인덱스의 버전을 모두 검색한 후 다음 인덱스로 이동한다.

unsafe-best-match:  모든 인덱스에서 패키지 이름을 검색하며, "최적" 버전을 우선시한다. 패키지 버전이 여러 인덱스에 있으면 첫 번째 인덱스의 항목만 확인한다.

--index-url, -i index-url
(사용 중단: --default-index 대신 사용) Python 패키지 인덱스의 URL을 지정한다(기본값: <https://pypi.org/simple>).

PEP 503을 준수하는 저장소(단순 저장소 API) 또는 동일한 형식의 로컬 디렉토리를 입력받는다.

이 플래그로 지정된 인덱스는 --extra-index-url 플래그로 지정된 모든 인덱스보다 낮은 우선순위를 가진다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--keyring-provider keyring-provider
인덱스 URL에 대한 인증을 위해 keyring 사용을 시도한다.

현재는 --keyring-provider subprocess만 지원하며, 이는 uv가 keyring CLI를 사용하도록 설정한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회에 keyring을 사용하지 않는다.

subprocess:  keyring 명령을 사용해 자격 증명을 조회한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 집합이며, uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 일부 경우, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-index
레지스트리 인덱스(예: PyPI)를 무시하고, 직접 URL 의존성과 --find-links로 제공된 것만 사용한다.

--no-progress
모든 진행률 출력을 숨긴다.

예: 스피너 또는 진행률 막대.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--outdated
업데이트가 필요한 패키지를 나열한다.

각 패키지의 최신 버전과 설치된 버전을 함께 표시한다. 최신 버전인 패키지는 출력에서 제외된다.

--project project
지정된 프로젝트 디렉토리 내에서 명령을 실행한다.

모든 pyproject.toml, uv.toml, .python-version 파일은 프로젝트 루트에서 디렉토리 트리를 올라가며 검색되며, 프로젝트의 가상 환경(.venv)도 마찬가지이다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python, -p python
패키지를 나열할 Python 인터프리터를 지정한다.

기본적으로 uv는 가상 환경의 패키지를 나열하지만, 가상 환경이 없으면 시스템 Python 환경의 패키지를 표시한다.

Python 검색 및 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참조한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선시할지 지정한다.

기본적으로 uv는 자신이 관리하는 Python 버전을 우선시한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선시하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용하며, 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선시한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선시한다.

only-system:  시스템 Python 설치만 사용하며, 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
출력하지 않는다.

--strict
Python 환경을 검증하여 누락된 의존성이 있는 패키지와 기타 문제를 감지한다.

--system
시스템 Python 환경의 패키지를 나열한다.

가상 환경 검색을 비활성화한다.

Python 검색에 대한 자세한 내용은 uv python을 참조한다.

UV_SYSTEM_PYTHON 환경 변수로도 설정할 수 있다.
--verbose, -v
자세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv pip show

설치된 패키지에 대한 정보를 표시한다.

사용법

uv pip show [OPTIONS] [PACKAGE]...


인자

PACKAGE
표시할 패키지



옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 보안되지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소와 검증되지 않는다. --allow-insecure-host는 SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크와 출처에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉터리 경로를 지정한다.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉터리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 터미널이나 TTY로 전송될 때만 색상 출력을 활성화한다.

always:  환경과 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정 파일 uv.toml의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령어 실행 전에 지정된 디렉터리로 이동한다.

상대 경로는 지정된 디렉터리를 기준으로 해석된다.

프로젝트 루트 디렉터리만 변경하려면 --project를 참조한다.

--files, -f
각 패키지에 설치된 파일의 전체 목록을 표시한다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla에서 제공하는 신뢰할 수 있는 루트 인증서 집합으로, uv에 포함되어 이식성과 성능(특히 macOS에서)을 향상시킨다.

하지만, 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용해야 하는 경우 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉터리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉터리, 상위 디렉터리, 또는 사용자 설정 디렉터리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상태 출력을 숨긴다.

예: 스피너 또는 진행 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
지정된 프로젝트 디렉터리 내에서 명령어를 실행한다.

프로젝트 루트에서 시작해 디렉터리 트리를 탐색하며 pyproject.toml, uv.toml, .python-version 파일을 검색한다. 프로젝트의 가상 환경(.venv)도 검색된다.

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉터리를 기준으로 해석된다.

작업 디렉터리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python, -p python
패키지를 찾을 Python 인터프리터를 지정한다.

기본적으로 uv는 가상 환경에서 패키지를 찾지만, 가상 환경이 없으면 시스템 Python 환경에서 패키지를 찾는다.

Python 검색과 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참조한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 지정한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 하지만 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리하는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리하는 Python 설치를 우선한다.

system:  관리하는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system:  시스템 Python 설치만 사용한다. 관리하는 Python 설치를 사용하지 않는다.

--quiet, -q
출력을 표시하지 않는다.

--strict
Python 환경을 검증하여 누락된 종속성과 기타 문제를 감지한다.

--system
시스템 Python 환경에서 패키지를 표시한다.

가상 환경 검색을 비활성화한다.

Python 검색에 대한 자세한 내용은 uv python을 참조한다.

UV_SYSTEM_PYTHON 환경 변수로도 설정할 수 있다.
--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv pip tree

환경의 의존성 트리를 표시한다.

사용법

uv pip tree [OPTIONS]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 안전하지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로 신뢰할 수 있는 네트워크와 검증된 소스에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉터리의 경로를 지정한다.

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉터리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전달될 때만 색상 출력을 활성화한다.

always:  환경에 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
구성을 위해 사용할 uv.toml 파일의 경로를 지정한다.

uv 구성은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--default-index default-index
기본 패키지 인덱스의 URL을 지정한다(기본값: <https://pypi.org/simple>).

PEP 503(단순 리포지토리 API)을 준수하는 리포지토리나 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 지정된 인덱스는 --index 플래그로 지정된 모든 다른 인덱스보다 낮은 우선순위를 가진다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--depth, -d depth
의존성 트리의 최대 표시 깊이를 지정한다.

[기본값: 255]
--directory directory
명령어를 실행하기 전에 주어진 디렉터리로 이동한다.

상대 경로는 주어진 디렉터리를 기준으로 해결된다.

프로젝트 루트 디렉터리만 변경하려면 --project를 참조한다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z)나 시스템의 시간대에 따른 동일한 형식의 로컬 날짜(예: 2006-12-02)를 받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra-index-url extra-index-url
(사용 중단: --index를 대신 사용) --index-url에 추가로 사용할 패키지 인덱스의 URL을 지정한다.

PEP 503(단순 리포지토리 API)을 준수하는 리포지토리나 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 제공된 모든 인덱스는 --index-url로 지정된 인덱스(기본값은 PyPI)보다 높은 우선순위를 가진다. 여러 --extra-index-url 플래그가 제공되면 먼저 제공된 값이 우선순위를 가진다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스에서 찾은 것 외에 후보 배포판을 검색할 위치를 지정한다.

경로인 경우, 대상은 최상위 레벨에 휠 파일(.whl)이나 소스 배포판(예: .tar.gz 또는 .zip)을 포함한 디렉터리여야 한다.

URL인 경우, 페이지는 위에서 설명한 형식에 맞는 패키지 파일에 대한 링크의 평면 목록을 포함해야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--help, -h
이 명령어에 대한 간결한 도움말을 표시한다.

--index index
기본 인덱스 외에 의존성을 해결할 때 사용할 URL을 지정한다.

PEP 503(단순 리포지토리 API)을 준수하는 리포지토리나 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 제공된 모든 인덱스는 --default-index로 지정된 인덱스(기본값은 PyPI)보다 높은 우선순위를 가진다. 여러 --index 플래그가 제공되면 먼저 제공된 값이 우선순위를 가진다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 해결할 때 사용할 전략을 지정한다.

기본적으로 uv는 주어진 패키지가 사용 가능한 첫 번째 인덱스에서 멈추고, 해당 첫 번째 인덱스에 있는 것만으로 해결을 제한한다(first-index). 이는 공격자가 동일한 이름으로 악성 패키지를 대체 인덱스에 업로드할 수 있는 "의존성 혼동" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  주어진 패키지 이름에 대해 일치하는 첫 번째 인덱스의 결과만 사용한다.

unsafe-first-match:  모든 인덱스에서 모든 패키지 이름을 검색하고, 첫 번째 인덱스의 버전을 모두 사용한 후 다음 인덱스로 이동한다.

unsafe-best-match:  모든 인덱스에서 모든 패키지 이름을 검색하고, "최선" 버전을 우선시한다. 패키지 버전이 여러 인덱스에 있는 경우, 첫 번째 인덱스의 항목만 확인한다.

--index-url, -i index-url
(사용 중단: --default-index를 대신 사용) Python 패키지 인덱스의 URL을 지정한다(기본값: <https://pypi.org/simple>).

PEP 503(단순 리포지토리 API)을 준수하는 리포지토리나 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 지정된 인덱스는 --extra-index-url 플래그로 지정된 모든 다른 인덱스보다 낮은 우선순위를 가진다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--invert
주어진 패키지에 대한 역의존성을 표시한다. 이 플래그는 트리를 뒤집어 주어진 패키지에 의존하는 패키지를 표시한다.

--keyring-provider keyring-provider
인덱스 URL에 대한 인증을 위해 keyring을 사용하려고 시도한다.

현재는 --keyring-provider subprocess만 지원되며, 이는 uv가 인증을 처리하기 위해 keyring CLI를 사용하도록 설정한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회에 keyring을 사용하지 않는다.

subprocess:  자격 증명 조회를 위해 keyring 명령어를 사용한다.

--native-tls
플랫폼의 네이티브 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 집합이며, 이를 uv에 포함시키면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 기업 신뢰 루트(예: 필수 프록시)를 사용하려는 경우, 플랫폼의 네이티브 인증서 저장소를 사용하고 싶을 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉터리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
구성 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 구성 파일은 현재 디렉터리, 상위 디렉터리, 또는 사용자 구성 디렉터리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-dedupe
반복된 의존성을 중복 제거하지 않는다. 일반적으로 패키지가 이미 의존성을 표시한 경우, 이후 발생 시 의존성을 다시 표시하지 않고 (*)를 포함하여 이미 표시되었음을 나타낸다. 이 플래그는 중복을 반복 표시한다.

--no-index
레지스트리 인덱스(예: PyPI)를 무시하고, 직접 URL 의존성과 --find-links로 제공된 것만 사용한다.

--no-progress
모든 진행 상황 출력을 숨긴다.

예: 스피너나 진행률 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화된 경우, uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--outdated
트리의 각 패키지에 대해 사용 가능한 최신 버전을 표시한다.

--package package
지정된 패키지만 표시한다.

--project project
주어진 프로젝트 디렉터리 내에서 명령어를 실행한다.

모든 pyproject.toml, uv.toml, .python-version 파일은 프로젝트 루트에서 디렉터리 트리를 올라가며 검색되며, 프로젝트의 가상 환경(.venv)도 검색된다.

다른 명령줄 인수(예: 상대 경로)는 현재 작업 디렉터리를 기준으로 해결된다.

작업 디렉터리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--prune prune
의존성 트리 표시에서 주어진 패키지를 제거한다.

--python, -p python
패키지를 나열할 Python 인터프리터를 지정한다.

기본적으로 uv는 가상 환경의 패키지를 나열하지만, 가상 환경이 없으면 시스템 Python 환경의 패키지를 표시한다.

Python 검색 및 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참조한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선시할지 지정한다.

기본적으로 uv는 관리하는 Python 버전을 우선시한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션은 시스템 Python 설치를 우선시하거나 무시할 수 있게 한다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리하는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리하는 Python 설치를 우선시한다.

system:  관리하는 Python 설치보다 시스템 Python 설치를 우선시한다.

only-system:  시스템 Python 설치만 사용한다. 관리하는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--show-version-specifiers
각 패키지에 부과된 버전 제약 조건을 표시한다.

--strict
Python 환경을 검증하여 누락된 의존성과 다른 문제를 감지한다.

--system
시스템 Python 환경의 패키지를 나열한다.

가상 환경 검색을 비활성화한다.

Python 검색에 대한 자세한 내용은 uv python을 참조한다.

UV_SYSTEM_PYTHON 환경 변수로도 설정할 수 있다.
--verbose, -v
상세 출력을 사용한다.

RUST_LOG 환경 변수를 사용하여 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv pip check

설치된 패키지의 의존성 호환성을 확인한다.

사용법

uv pip check [OPTIONS]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 보안되지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력한다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 소스가 있는 보안된 네트워크에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉터리의 경로를 지정한다.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉터리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전달될 때만 색상 출력을 활성화한다.

always:  환경과 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정에 사용할 uv.toml 파일의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 지정된 디렉터리로 이동한다.

상대 경로는 지정된 디렉터리를 기준으로 해석된다.

--project를 참조해 프로젝트 루트 디렉터리만 변경할 수 있다.

--help, -h
이 명령에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, 이를 uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

하지만 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용해야 할 때는 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉터리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 탐색하지 않는다.

일반적으로 설정 파일은 현재 디렉터리, 상위 디렉터리, 또는 사용자 설정 디렉터리에서 탐색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄이 포함된다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
지정된 프로젝트 디렉터리 내에서 명령을 실행한다.

프로젝트 루트에서 디렉터리 트리를 탐색하며 pyproject.toml, uv.toml, .python-version 파일을 찾고, 프로젝트의 가상 환경(.venv)도 탐색한다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉터리를 기준으로 해석된다.

작업 디렉터리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python, -p python
패키지를 확인할 Python 인터프리터를 지정한다.

기본적으로 uv는 가상 환경에서 패키지를 확인하지만, 가상 환경이 없으면 시스템 Python 환경에서 패키지를 확인한다.

Python 탐색 및 지원되는 요청 형식에 대한 자세한 내용은 uv python을 참조한다.

UV_PYTHON 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 지정한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 하지만 uv가 관리하는 Python이 설치되지 않았을 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system:  시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
출력을 표시하지 않는다.

--system
시스템 Python 환경에서 패키지를 확인한다.

가상 환경 탐색을 비활성화한다.

Python 탐색에 대한 자세한 내용은 uv python을 참조한다.

UV_SYSTEM_PYTHON 환경 변수로도 설정할 수 있다.
--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




## 가상 환경 생성

가상 환경을 생성한다.

기본적으로 작업 디렉토리에 `.venv`라는 이름의 가상 환경을 만든다. 다른 경로를 지정할 수도 있다.

프로젝트 내부라면 `UV_PROJECT_ENVIRONMENT` 환경 변수를 통해 기본 환경 이름을 변경할 수 있다. 이 설정은 프로젝트 루트 디렉토리에서 실행할 때만 적용된다.

대상 경로에 가상 환경이 이미 존재하면, 해당 환경을 제거하고 새로운 빈 가상 환경을 생성한다.

uv를 사용할 때는 가상 환경을 활성화할 필요가 없다. uv는 작업 디렉토리나 상위 디렉토리에서 `.venv`라는 이름의 가상 환경을 자동으로 찾는다.

사용법

uv venv [옵션] [경로]


인자

경로
생성할 가상 환경의 경로.

기본값은 작업 디렉토리 내의 .venv이다.

상대 경로는 작업 디렉토리를 기준으로 해석된다.



옵션

--allow-existing
대상 경로에 있는 기존 파일이나 디렉토리를 보존한다.

기본적으로 uv venv는 주어진 경로에 있는 기존 가상 환경을 제거한다. 경로가 비어 있지 않지만 가상 환경이 아닌 경우에는 오류를 발생시킨다. --allow-existing 옵션을 사용하면 경로의 내용을 지우지 않고 그대로 사용한다.

경고: 기존 가상 환경과 새로 생성된 가상 환경이 서로 다른 Python 인터프리터에 연결되어 있다면 예기치 않은 동작이 발생할 수 있다.

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 지정할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력한다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소와 비교해 검증되지 않는다. SSL 검증을 우회하므로 MITM 공격에 노출될 수 있다. 신뢰할 수 있는 네트워크에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에 색상을 사용할지 여부를 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  터미널이나 TTY에 출력할 때만 색상을 사용

always:  환경과 상관없이 항상 색상을 사용

never:  색상을 사용하지 않음

--config-file config-file
설정 파일 uv.toml의 경로.

uv 설정은 pyproject.toml 파일에 포함할 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--default-index default-index
기본 패키지 인덱스의 URL (기본값: <https://pypi.org/simple>).

PEP 503을 준수하는 저장소나 동일한 형식의 로컬 디렉토리를 입력한다.

이 플래그로 지정된 인덱스는 --index 플래그로 지정된 모든 인덱스보다 우선순위가 낮다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 주어진 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지만 후보로 고려한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z)나 시스템의 시간대에 맞는 로컬 날짜(예: 2006-12-02)를 입력한다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra-index-url extra-index-url
(더 이상 사용되지 않음: --index를 대신 사용) 추가 패키지 인덱스 URL.

PEP 503을 준수하는 저장소나 동일한 형식의 로컬 디렉토리를 입력한다.

이 플래그로 지정된 모든 인덱스는 --index-url로 지정된 인덱스(기본값은 PyPI)보다 우선순위가 높다. 여러 --extra-index-url 플래그를 사용하면 먼저 지정된 값이 우선순위가 높다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스 외에 추가로 검색할 패키지 위치.

경로를 지정하면, 대상 디렉토리의 최상위에 있는 휠 파일(.whl)이나 소스 배포판(예: .tar.gz 또는 .zip)을 검색한다.

URL을 지정하면, 패키지 파일에 대한 링크가 포함된 평면 목록이 있어야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--help, -h
이 명령에 대한 간단한 도움말을 표시한다.

--index index
기본 인덱스 외에 의존성을 해결할 때 사용할 URL.

PEP 503을 준수하는 저장소나 동일한 형식의 로컬 디렉토리를 입력한다.

이 플래그로 지정된 모든 인덱스는 --default-index로 지정된 인덱스(기본값은 PyPI)보다 우선순위가 높다. 여러 --index 플래그를 사용하면 먼저 지정된 값이 우선순위가 높다.

UV_INDEX 환경 변수로도 설정할 수 있다.
--index-strategy index-strategy
여러 인덱스 URL에 대해 의존성을 해결할 때 사용할 전략.

기본적으로 uv는 특정 패키지가 처음 발견된 인덱스에서만 결과를 사용하고, 그 인덱스에 있는 버전으로만 해결한다(first-index). 이는 악의적인 패키지를 대체 인덱스에 업로드하는 "의존성 혼동" 공격을 방지한다.

UV_INDEX_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


first-index:  특정 패키지가 처음 발견된 인덱스의 결과만 사용

unsafe-first-match:  모든 인덱스에서 패키지 이름을 검색하고, 첫 번째 인덱스의 버전을 모두 사용한 후 다음 인덱스로 이동

unsafe-best-match:  모든 인덱스에서 패키지 이름을 검색하고, "가장 좋은" 버전을 우선 선택. 여러 인덱스에 동일한 패키지 버전이 있으면 첫 번째 인덱스의 항목만 고려

--index-url, -i index-url
(더 이상 사용되지 않음: --default-index를 대신 사용) Python 패키지 인덱스의 URL (기본값: <https://pypi.org/simple>).

PEP 503을 준수하는 저장소나 동일한 형식의 로컬 디렉토리를 입력한다.

이 플래그로 지정된 인덱스는 --extra-index-url 플래그로 지정된 모든 인덱스보다 우선순위가 낮다.

UV_INDEX_URL 환경 변수로도 설정할 수 있다.
--keyring-provider keyring-provider
인덱스 URL에 대한 인증을 위해 keyring을 사용한다.

현재는 --keyring-provider subprocess만 지원하며, 이는 uv가 keyring CLI를 사용해 인증을 처리하도록 설정한다.

기본값은 disabled이다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  keyring을 사용하지 않음

subprocess:  keyring 명령을 사용해 인증 처리

--link-mode link-mode
전역 캐시에서 패키지를 설치할 때 사용할 방법.

이 옵션은 시드 패키지를 설치할 때만 사용된다.

기본값은 macOS에서는 clone(Copy-on-Write), Linux와 Windows에서는 hardlink이다.

UV_LINK_MODE 환경 변수로도 설정할 수 있다.
가능한 값:


clone:  휠에서 site-packages 디렉토리로 패키지를 복제(Copy-on-Write)

copy:  휠에서 site-packages 디렉토리로 패키지를 복사

hardlink:  휠에서 site-packages 디렉토리로 패키지를 하드 링크

symlink:  휠에서 site-packages 디렉토리로 패키지를 심볼릭 링크

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, uv에 포함되어 이식성과 성능(특히 macOS에서)을 향상시킨다.

하지만 일부 경우, 특히 기업의 신뢰 루트(예: 필수 프록시)가 시스템의 인증서 저장소에 포함되어 있다면, 플랫폼의 기본 인증서 저장소를 사용하고 싶을 수도 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시를 읽거나 쓰지 않고, 작업 중에 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 현재 디렉토리, 상위 디렉토리, 사용자 설정 디렉토리에서 설정 파일을 검색한다.

UV_NO_CONFIG 환경 변수로도 설정할


## uv build

Python 패키지를 소스 배포판(sdist)과 바이너리 배포판(wheel)으로 빌드한다.

`uv build`는 디렉터리나 소스 배포판 경로를 인자로 받으며, 기본값은 현재 작업 디렉터리다.

디렉터리를 전달하면 `uv build`는 기본적으로 소스 디렉터리에서 소스 배포판(sdist)을 빌드하고, 소스 배포판에서 바이너리 배포판(wheel)을 빌드한다.

`uv build --sdist`는 소스 배포판만 빌드하고, `uv build --wheel`은 바이너리 배포판만 빌드한다. `uv build --sdist --wheel`은 소스에서 두 배포판을 모두 빌드한다.

소스 배포판을 전달하면 `uv build --wheel`은 소스 배포판에서 바이너리 배포판을 빌드한다.

사용법

uv build [OPTIONS] [SRC]


인자

SRC
배포판을 빌드할 디렉터리 또는 바이너리 배포판으로 빌드할 소스 배포판 아카이브.

기본값은 현재 작업 디렉터리.



옵션

--all-packages
워크스페이스의 모든 패키지를 빌드한다.

소스 디렉터리에서 워크스페이스를 탐색하며, 소스 디렉터리가 제공되지 않으면 현재 디렉터리를 사용한다.

워크스페이스 멤버가 없으면 uv는 오류와 함께 종료된다.

--allow-insecure-host allow-insecure-host
호스트에 대한 안전하지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 안전한 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--build-constraints, -b build-constraints
배포판을 빌드할 때 주어진 요구사항 파일을 사용해 빌드 종속성을 제한한다.

제약 파일은 requirements.txt와 유사한 파일로, 설치된 빌드 종속성의 버전만 제어한다. 그러나 제약 파일에 패키지를 포함해도 해당 패키지가 자동으로 포함되지는 않는다.

UV_BUILD_CONSTRAINT 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉터리 경로.

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서 %LOCALAPPDATA%\uv\cache다.

캐시 디렉터리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 터미널이나 TTY로 전달될 때만 색상 출력을 활성화

always:  감지된 환경에 관계없이 항상 색상 출력을 활성화

never:  색상 출력을 비활성화

--config-file config-file
설정에 사용할 uv.toml 파일 경로.

uv 설정은 pyproject.toml 파일에 포함할 수 있지만, 이 컨텍스트에서는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--config-setting, -C config-setting
PEP 517 빌드 백엔드에 전달할 설정을 KEY=VALUE 쌍으로 지정

--default-index default-index
기본 패키지 인덱스 URL (기본값: <https://pypi.org/simple>).

PEP 503(간단한 리포지토리 API)을 준수하는 리포지토리 또는 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 제공된 인덱스는 --index 플래그로 지정된 모든 다른 인덱스보다 우선순위가 낮다.

UV_DEFAULT_INDEX 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 주어진 디렉터리로 변경한다.

상대 경로는 주어진 디렉터리를 기준으로 해석된다.

프로젝트 루트 디렉터리만 변경하려면 --project를 참조한다.

--exclude-newer exclude-newer
주어진 날짜 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 타임스탬프(예: 2006-12-02T02:07:43Z) 또는 시스템의 시간대에 맞춘 동일한 형식의 로컬 날짜(예: 2006-12-02)를 받는다.

UV_EXCLUDE_NEWER 환경 변수로도 설정할 수 있다.
--extra-index-url extra-index-url
(사용 중단: --index 대신 사용) --index-url 외에 사용할 추가 패키지 인덱스 URL.

PEP 503(간단한 리포지토리 API)을 준수하는 리포지토리 또는 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 제공된 모든 인덱스는 --index-url(기본값은 PyPI)로 지정된 인덱스보다 우선순위가 높다. 여러 --extra-index-url 플래그를 제공하면 이전 값이 우선순위를 가진다.

UV_EXTRA_INDEX_URL 환경 변수로도 설정할 수 있다.
--find-links, -f find-links
레지스트리 인덱스 외에 후보 배포판을 검색할 위치.

경로를 제공하면 대상은 최상위 레벨에 휠 파일(.whl) 또는 소스 배포판(예: .tar.gz 또는 .zip)이 포함된 디렉터리여야 한다.

URL을 제공하면 페이지는 위에서 설명한 형식의 패키지 파일에 대한 링크 목록을 포함해야 한다.

UV_FIND_LINKS 환경 변수로도 설정할 수 있다.
--force-pep517
항상 PEP 517을 통해 빌드하며, uv 빌드 백엔드에 대한 빠른 경로를 사용하지 않는다.

기본적으로 uv는 uv 빌드 백엔드를 사용하는 패키지에 대해 PEP 517 빌드 환경을 생성하지 않고, 빌드 백엔드에 직접 호출하는 빠른 경로를 사용한다. 이 옵션은 항상 PEP 517을 사용하도록 강제한다.

--fork-strategy fork-strategy
여러 Python 버전과 플랫폼에서 주어진 패키지의 여러 버전을 선택할 때 사용할 전략.

기본적으로 uv는 지원되는 Python 버전(requires-python)에 대해 각 패키지의 최신 버전을 선택하도록 최적화하며, 플랫폼 간 선택된 버전 수를 최소화한다.

fewest 옵션을 사용하면 uv는 각 패키지에 대해 선택된 버전 수를 최소화하며, 지원되는 Python 버전 또는 플랫폼 범위가 더 넓은 이전 버전을 선호한다.

UV_FORK_STRATEGY 환경 변수로도 설정할 수 있다.
가능한 값:


fewest:  각 패키지에 대해 선택된 버전 수를 최소화하도록 최적화. 지원되는 Python 버전 또는 플랫폼 범위가 더 넓은 이전 버전을 선호

requires-python:  지원되는 Python 버전에 대해 각 패키지의 최신 지원 버전을 선택하도록 최적화

--help, -h
이 명령에 대한 간결한 도움말을 표시

--index index
종속성을 해결할 때 사용할 URL을 기본 인덱스 외에 추가.

PEP 503(간단한 리포지토리 API)을 준수하는 리포지토리 또는 동일한 형식의 로컬 디렉터리를 받는다.

이 플래그로 제공된 모든 인덱스는 --default-index(기본값은 PyPI)로 지정된 인덱스보다 우선순위가 높다. 여러 --index 플래그를 제공하면 이전 값이 우선순위를 가진다.

UV_INDEX 환경 변수로도 설정할


## uv publish

배포 파일을 인덱스에 업로드한다.

사용법

uv publish [OPTIONS] [FILES]...


인자

FILES
업로드할 파일 경로. glob 표현식을 지원한다.

기본값은 dist 디렉토리다. 휠 파일과 소스 배포 파일만 선택하며, 다른 파일은 무시한다.



옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 보안되지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소와 대조해 검증하지 않는다. SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크와 소스에서만 사용해야 한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache다.

캐시 디렉토리 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--check-url check-url
기존 파일을 확인하기 위해 인덱스 URL을 검사해 중복 업로드를 건너뛴다.

이 옵션은 일부 파일만 업로드된 후 실패한 경우 재시도할 수 있게 하며, 동일한 파일의 병렬 업로드로 인한 오류를 처리한다.

업로드 전에 인덱스를 확인한다. 동일한 파일이 이미 인덱스에 존재하면 업로드하지 않는다. 업로드 중 오류가 발생하면 인덱스를 다시 확인해 동일한 파일이 병렬로 두 번 업로드된 경우를 처리한다.

정확한 동작은 인덱스에 따라 다르다. PyPI에 업로드할 때는 --check-url 없이도 동일한 파일 업로드가 성공하지만, 대부분의 다른 인덱스에서는 오류가 발생한다.

인덱스는 지원되는 해시(SHA-256, SHA-384, 또는 SHA-512) 중 하나를 제공해야 한다.

UV_PUBLISH_CHECK_URL 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전달될 때만 색상 출력을 활성화한다.

always:  환경에 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정에 사용할 uv.toml 파일 경로.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령어 실행 전 주어진 디렉토리로 변경한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참고한다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다.

--index index
업로드에 사용할 설정 파일의 인덱스 이름.

인덱스는 publish-url 설정이 있어야 한다. 예를 들어:

인덱스 `url`은 기존 파일을 확인해 중복 업로드를 건너뛰는 데 사용된다.

이 설정을 사용하면 다음 두 호출은 동일하다:

UV_PUBLISH_INDEX 환경 변수로도 설정할 수 있다.
--keyring-provider keyring-provider
원격 요구 사항 파일에 대한 인증을 위해 keyring 사용을 시도한다.

현재는 --keyring-provider subprocess만 지원하며, 이는 uv가 keyring CLI를 사용해 인증을 처리하도록 설정한다.

기본값은 disabled다.

UV_KEYRING_PROVIDER 환경 변수로도 설정할 수 있다.
가능한 값:


disabled:  자격 증명 조회에 keyring을 사용하지 않는다.

subprocess:  keyring 커맨드를 사용해 자격 증명을 조회한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, 이를 uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리, 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄을 숨긴다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--password, -p password
업로드에 사용할 비밀번호.

UV_PUBLISH_PASSWORD 환경 변수로도 설정할 수 있다.
--project project
주어진 프로젝트 디렉토리 내에서 명령어를 실행한다.

프로젝트 루트에서 디렉토리 트리를 따라 올라가면서 모든 pyproject.toml, uv.toml, .python-version 파일을 검색하며, 프로젝트의 가상 환경(.venv)도 검색한다.

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참고한다.

이 설정은 uv pip 인터페이스에서 사용할 때는 효과가 없다.

--publish-url publish-url
업로드 엔드포인트 URL(인덱스 URL이 아님).

일반적으로 인덱스 접근(예: https:://.../simple)과 인덱스 업로드 URL은 다르다.

기본값은 PyPI의 업로드 URL(<https://upload.pypi.org/legacy/>)이다.

UV_PUBLISH_URL 환경 변수로도 설정할 수 있다.
--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 설정한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 그러나 관리되는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용하며, 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system:  시스템 Python 설치만 사용하며, 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--token, -t token
업로드에 사용할 토큰.

토큰을 사용하는 것은 --username에 __token__을, --password에 토큰을 전달하는 것과 동일하다.

UV_PUBLISH_TOKEN 환경 변수로도 설정할 수 있다.
--trusted-publishing trusted-publishing
GitHub Actions를 통한 신뢰할 수 있는 게시를 설정한다.

기본적으로 uv는 GitHub Actions에서 실행될 때 신뢰할 수 있는 게시를 확인하지만, 설정되지 않았거나 워크플로에 충분한 권한이 없는 경우(예: 포크에서의 풀 리퀘스트) 무시한다.

가능한 값:


automatic:  GitHub Actions에서 실행 중일 때 신뢰할 수 있는 게시를 시도하고, 실패하면 계속 진행한다.

always

never

--username, -u username
업로드에 사용할 사용자 이름.

UV_PUBLISH_USERNAME 환경 변수로도 설정할 수 있다.
--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 설정할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




## uv 캐시 관리

uv의 캐시를 관리한다.

사용법

uv cache [OPTIONS] <COMMAND>


커맨드

uv cache clean
캐시를 지우고, 모든 항목이나 특정 패키지와 연결된 항목을 제거한다

uv cache prune
캐시에서 도달할 수 없는 모든 객체를 정리한다

uv cache dir
캐시 디렉토리를 표시한다




### uv cache clean

캐시를 정리하여 모든 항목이나 특정 패키지와 연결된 항목을 제거한다.

사용법

uv cache clean [OPTIONS] [PACKAGE]...


인자

PACKAGE
캐시에서 제거할 패키지



옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 보안되지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 보안 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉터리의 경로.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉터리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전송될 때만 색상 출력을 활성화한다.

always:  감지된 환경과 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정에 사용할 uv.toml 파일의 경로.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령어 실행 전에 주어진 디렉터리로 변경한다.

상대 경로는 주어진 디렉터리를 기준으로 해석된다.

프로젝트 루트 디렉터리만 변경하려면 --project를 참조한다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, 이를 uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 기업 신뢰 루트(예: 필수 프록시)를 사용하려는 경우 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉터리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉터리, 상위 디렉터리 또는 사용자 설정 디렉터리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화된 경우, uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
주어진 프로젝트 디렉터리 내에서 명령어를 실행한다.

프로젝트 루트에서 디렉터리 트리를 올라가며 pyproject.toml, uv.toml, .python-version 파일과 프로젝트의 가상 환경(.venv)을 검색한다.

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉터리를 기준으로 해석된다.

작업 디렉터리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 결정한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system:  시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### uv cache prune

캐시에서 도달할 수 없는 모든 객체를 제거한다.

사용법

uv cache prune [OPTIONS]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 보안 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로를 지정한다.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--ci
GitHub Actions 같은 지속적 통합 환경에서 캐시를 최적화한다.

기본적으로 uv는 소스에서 빌드한 휠과 직접 다운로드한 사전 빌드된 휠을 모두 캐시한다. 그러나 GitHub Actions 같은 환경에서는 사전 빌드된 휠을 캐시하지 않고 매번 다시 다운로드하는 것이 더 빠를 수 있다. 반면, 소스에서 빌드한 휠은 캐시하는 것이 일반적으로 더 빠르다.

--ci 모드에서 uv는 사전 빌드된 휠을 캐시에서 제거하지만, 소스에서 빌드한 휠은 유지한다.

--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  터미널이나 TTY에 출력할 때만 색상 출력을 활성화한다.

always:  환경에 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정에 사용할 uv.toml 파일의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 지정된 디렉토리로 이동한다.

상대 경로는 지정된 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--help, -h
이 명령에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, 이를 uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 일부 경우, 특히 시스템의 인증서 저장소에 포함된 기업용 루트 인증서(예: 필수 프록시)를 사용하려면 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리, 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄을 숨긴다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
지정된 프로젝트 디렉토리 내에서 명령을 실행한다.

프로젝트 루트에서 디렉토리 트리를 따라 pyproject.toml, uv.toml, .python-version 파일과 프로젝트의 가상 환경(.venv)을 검색한다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 지정한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 사용하면 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system:  시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




### 캐시 디렉토리 확인

캐시 디렉토리의 위치를 확인한다.

기본적으로 캐시는 Unix 시스템에서는 `$XDG_CACHE_HOME/uv` 또는 `$HOME/.cache/uv`에 저장되고, Windows에서는 `%LOCALAPPDATA%\uv\cache`에 저장된다.

`--no-cache` 옵션을 사용하면 캐시는 임시 디렉토리에 저장되며, 프로세스가 종료되면 삭제된다.

다른 캐시 디렉토리를 지정하려면 `cache-dir` 설정, `--cache-dir` 옵션, 또는 `$UV_CACHE_DIR` 환경 변수를 사용한다.

캐시 디렉토리가 uv가 동작하는 Python 환경과 동일한 파일 시스템에 위치하는 것이 성능에 중요하다는 점에 유의한다.

사용법

uv cache dir [OPTIONS]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 보안 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로를 지정한다.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv이고, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전송될 때만 색상 출력을 활성화한다.

always:  환경 감지와 상관없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정에 사용할 uv.toml 파일의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령어 실행 전에 주어진 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참고한다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합으로, uv에 포함되어 이식성과 성능(특히 macOS에서)을 향상시킨다.

하지만 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 기업 신뢰 루트(예: 필수 프록시)를 사용해야 할 때는 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리, 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄 등이 있다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
주어진 프로젝트 디렉토리 내에서 명령어를 실행한다.

프로젝트 루트에서 시작해 디렉토리 트리를 탐색하며 pyproject.toml, uv.toml, .python-version 파일을 찾는다. 또한 프로젝트의 가상 환경(.venv)도 검색된다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참고한다.

이 설정은 uv pip 인터페이스에서 사용할 때는 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 지정한다.

기본적으로 uv는 자체적으로 관리하는 Python 버전을 우선 사용한다. 하지만 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  uv가 관리하는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 uv가 관리하는 Python 설치를 우선한다.

system:  uv가 관리하는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system:  시스템 Python 설치만 사용한다. uv가 관리하는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




## uv self

uv 실행 파일 관리

사용법

uv self [OPTIONS] <COMMAND>


커맨드

uv self update
uv 업데이트




### uv 자동 업데이트

uv를 업데이트한다.

사용법

uv self update [OPTIONS] [TARGET_VERSION]


인자

TARGET_VERSION
지정한 버전으로 업데이트한다. 인자를 제공하지 않으면 최신 버전으로 업데이트한다.



옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 보안되지 않은 연결을 허용한다.

여러 번 제공할 수 있다.

호스트 이름(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하고 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크와 소스에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로를 지정한다.

기본값은 macOS와 Linux에서 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto: 출력이 터미널이나 TTY로 전달될 때만 색상 출력을 활성화한다.

always: 환경과 상관없이 항상 색상 출력을 활성화한다.

never: 색상 출력을 비활성화한다.

--config-file config-file
설정에 사용할 uv.toml 파일의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령을 실행하기 전에 지정한 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참고한다.

--help, -h
이 명령에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 결정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합으로, uv에 포함되어 이식성과 성능(특히 macOS에서)을 향상시킨다.

하지만 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용해야 할 때는 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리, 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어, 스피너나 진행률 표시줄이 포함된다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
지정한 프로젝트 디렉토리 내에서 명령을 실행한다.

프로젝트 루트에서 디렉토리 트리를 따라 올라가면서 pyproject.toml, uv.toml, .python-version 파일을 검색하고, 프로젝트의 가상 환경(.venv)도 찾는다.

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참고한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 결정한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 하지만 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed: 관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed: 시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

system: 관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system: 시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
출력을 표시하지 않는다.

--token token
인증을 위한 GitHub 토큰을 지정한다. 토큰은 필수는 아니지만, rate limit에 걸릴 가능성을 줄일 수 있다.

UV_GITHUB_TOKEN 환경 변수로도 설정할 수 있다.
--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




## uv 버전 확인

uv의 버전을 표시한다.

사용법

uv version [OPTIONS]


옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 소스가 있는 보안 네트워크에서만 --allow-insecure-host를 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로를 지정한다.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전송될 때만 색상 출력을 활성화한다.

always:  환경 감지와 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
구성 파일인 uv.toml의 경로를 지정한다.

uv 구성은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령어를 실행하기 전에 주어진 디렉토리로 변경한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 신뢰 루트 집합이며, uv에 포함되어 이식성과 성능(특히 macOS에서)을 향상시킨다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 회사 신뢰 루트(예: 필수 프록시)를 사용하려는 경우 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
구성 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 구성 파일은 현재 디렉토리, 상위 디렉토리 또는 사용자 구성 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-progress
모든 진행 상황 출력을 숨긴다.

예를 들어 스피너나 진행률 표시줄 등이 포함된다.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화되면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--output-format output-format
--project project
주어진 프로젝트 디렉토리 내에서 명령어를 실행한다.

프로젝트 루트에서 디렉토리 트리를 탐색하여 pyproject.toml, uv.toml, .python-version 파일을 발견할 수 있으며, 프로젝트의 가상 환경(.venv)도 발견할 수 있다.

다른 커맨드라인 인수(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 지정한다.

기본적으로 uv는 자체적으로 관리하는 Python 버전을 우선 사용한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용하며, 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system:  시스템 Python 설치만 사용하며, 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용하여 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.




## uv generate-shell-completion

쉘 자동 완성 스크립트 생성

사용법

uv generate-shell-completion [옵션] <SHELL>


인자

SHELL
자동 완성 스크립트를 생성할 쉘



옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결 허용

여러 번 제공 가능

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 입력받음

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않음. SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 신뢰할 수 있는 네트워크와 출처에서만 --allow-insecure-host를 사용할 것

UV_INSECURE_HOST 환경 변수로도 설정 가능
--directory directory
명령어 실행 전 주어진 디렉토리로 이동

상대 경로는 주어진 디렉토리를 기준으로 해석됨

프로젝트 루트 디렉토리만 변경하려면 --project 참조

--project project
주어진 프로젝트 디렉토리 내에서 명령어 실행

프로젝트 루트부터 상위 디렉토리 트리를 탐색하며 pyproject.toml, uv.toml, .python-version 파일을 찾음. 프로젝트의 가상 환경(.venv)도 동일하게 탐색됨

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석됨

작업 디렉토리를 완전히 변경하려면 --directory 참조

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없음




## uv help

명령어에 대한 문서를 표시한다.

사용법

uv help [OPTIONS] [COMMAND]...


인자

COMMAND

옵션

--allow-insecure-host allow-insecure-host
호스트에 대한 비보안 연결을 허용한다.

여러 번 제공할 수 있다.

호스트명(예: localhost), 호스트-포트 쌍(예: localhost:8080), 또는 URL(예: https://localhost)을 받는다.

경고: 이 목록에 포함된 호스트는 시스템의 인증서 저장소에 대해 검증되지 않는다. --allow-insecure-host는 SSL 검증을 우회하며 MITM 공격에 노출될 수 있으므로, 검증된 소스가 있는 보안 네트워크에서만 사용한다.

UV_INSECURE_HOST 환경 변수로도 설정할 수 있다.
--cache-dir cache-dir
캐시 디렉토리의 경로를 지정한다.

기본값은 macOS와 Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache이다.

캐시 디렉토리의 위치를 확인하려면 uv cache dir을 실행한다.

UV_CACHE_DIR 환경 변수로도 설정할 수 있다.
--color color-choice
출력에서 색상 사용을 제어한다.

기본적으로 uv는 터미널에 출력할 때 색상 지원을 자동으로 감지한다.

가능한 값:


auto:  출력이 색상을 지원하는 터미널이나 TTY로 전송될 때만 색상 출력을 활성화한다.

always:  감지된 환경에 관계없이 항상 색상 출력을 활성화한다.

never:  색상 출력을 비활성화한다.

--config-file config-file
설정에 사용할 uv.toml 파일의 경로를 지정한다.

uv 설정은 pyproject.toml 파일에 포함될 수 있지만, 이 경우에는 허용되지 않는다.

UV_CONFIG_FILE 환경 변수로도 설정할 수 있다.
--directory directory
명령어를 실행하기 전에 주어진 디렉토리로 이동한다.

상대 경로는 주어진 디렉토리를 기준으로 해석된다.

프로젝트 루트 디렉토리만 변경하려면 --project를 참조한다.

--help, -h
이 명령어에 대한 간단한 도움말을 표시한다.

--native-tls
플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드할지 여부를 지정한다.

기본적으로 uv는 번들된 webpki-roots 크레이트에서 인증서를 로드한다. webpki-roots는 Mozilla의 신뢰할 수 있는 루트 인증서 집합이며, 이를 uv에 포함하면 이식성과 성능(특히 macOS에서)이 향상된다.

그러나 경우에 따라, 특히 시스템의 인증서 저장소에 포함된 기업 신뢰 루트(예: 필수 프록시)를 사용해야 할 때는 플랫폼의 기본 인증서 저장소를 사용할 수 있다.

UV_NATIVE_TLS 환경 변수로도 설정할 수 있다.
--no-cache, -n
캐시에서 읽거나 쓰지 않고, 작업 기간 동안 임시 디렉토리를 사용한다.

UV_NO_CACHE 환경 변수로도 설정할 수 있다.
--no-config
설정 파일(pyproject.toml, uv.toml)을 검색하지 않는다.

일반적으로 설정 파일은 현재 디렉토리, 상위 디렉토리, 또는 사용자 설정 디렉토리에서 검색된다.

UV_NO_CONFIG 환경 변수로도 설정할 수 있다.
--no-pager
도움말을 출력할 때 페이저를 비활성화한다.

--no-progress
모든 진행 상황 출력을 숨긴다.

예: 스피너나 진행률 표시줄.

UV_NO_PROGRESS 환경 변수로도 설정할 수 있다.
--no-python-downloads
Python의 자동 다운로드를 비활성화한다.

--offline
네트워크 접근을 비활성화한다.

비활성화하면 uv는 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 사용한다.

UV_OFFLINE 환경 변수로도 설정할 수 있다.
--project project
주어진 프로젝트 디렉토리 내에서 명령어를 실행한다.

프로젝트 루트에서 시작해 디렉토리 트리를 올라가며 pyproject.toml, uv.toml, .python-version 파일을 검색한다. 또한 프로젝트의 가상 환경(.venv)도 검색된다.

다른 커맨드라인 인자(예: 상대 경로)는 현재 작업 디렉토리를 기준으로 해석된다.

작업 디렉토리를 완전히 변경하려면 --directory를 참조한다.

이 설정은 uv pip 인터페이스에서 사용할 때 효과가 없다.

--python-preference python-preference
uv가 관리하는 Python 설치와 시스템 Python 설치 중 어느 것을 우선할지 지정한다.

기본적으로 uv는 관리하는 Python 버전을 우선 사용한다. 그러나 uv가 관리하는 Python이 설치되지 않은 경우 시스템 Python 설치를 사용한다. 이 옵션을 통해 시스템 Python 설치를 우선하거나 무시할 수 있다.

UV_PYTHON_PREFERENCE 환경 변수로도 설정할 수 있다.
가능한 값:


only-managed:  관리되는 Python 설치만 사용한다. 시스템 Python 설치를 사용하지 않는다.

managed:  시스템 Python 설치보다 관리되는 Python 설치를 우선한다.

system:  관리되는 Python 설치보다 시스템 Python 설치를 우선한다.

only-system:  시스템 Python 설치만 사용한다. 관리되는 Python 설치를 사용하지 않는다.

--quiet, -q
어떤 출력도 표시하지 않는다.

--verbose, -v
상세한 출력을 사용한다.

RUST_LOG 환경 변수를 사용해 세부적인 로깅을 구성할 수 있다. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

--version, -V
uv 버전을 표시한다.