Settings

프로젝트 메타데이터¶

`build-constraint-dependencies` {: #build-constraint-dependencies }¶

빌드 종속성을 해결할 때 적용할 제약 조건.

빌드 제약 조건은 해결 또는 설치 과정에서 패키지를 빌드할 때 선택되는 빌드 종속성의 버전을 제한하는 데 사용한다.

패키지를 제약 조건으로 포함한다고 해서 빌드 중에 해당 패키지가 설치되지는 않는다. 대신, 프로젝트의 빌드 종속성 그래프에서 다른 곳에서 해당 패키지를 요청해야 한다.

주의

uv lock, uv sync, uv run 명령어를 사용할 때, uv는 워크스페이스 루트의 pyproject.toml에서만 build-constraint-dependencies를 읽으며, 다른 워크스페이스 멤버나 uv.toml 파일에 선언된 내용은 무시한다.

기본값: []

타입: list[str]

예제 사용법:

pyproject.toml

[tool.uv]
# setuptools에 대한 빌드 종속성이 있을 때 항상 setuptools v60.0.0을 사용하도록 보장.
build-constraint-dependencies = ["setuptools==60.0.0"]

`conflicts` {: #conflicts }¶

상호 배타적인 엑스트라 또는 의존성 그룹의 충돌을 선언한다.

두 개 이상의 엑스트라가 서로 호환되지 않는 의존성을 가질 때 충돌을 선언하는 것이 유용하다. 예를 들어, 엑스트라 foo는 numpy==2.0.0에 의존하고, 엑스트라 bar는 numpy==2.1.0에 의존할 수 있다. 이러한 의존성이 충돌하더라도 사용자가 동시에 foo와 bar를 활성화하지 않을 것으로 예상된다면, 호환성 문제에도 불구하고 프로젝트에 대한 보편적인 해결책을 생성할 수 있다.

이러한 충돌을 명시적으로 선언함으로써, uv는 특정 엑스트라와 그룹의 조합이 상호 배타적임을 고려하여 프로젝트에 대한 보편적인 해결책을 생성할 수 있다. 대신, 사용자가 충돌하는 엑스트라를 동시에 활성화하려고 하면 설치가 실패한다.

기본값: []

타입: list[list[dict]]

예제 사용법:

pyproject.toml

[tool.uv]
# `package[extra1]`과 `package[extra2]`가 서로 충돌하지 않도록
# 다른 포크에서 해결되도록 요구한다.
conflicts = [
    [
        { extra = "extra1" },
        { extra = "extra2" },
    ]
]

# 의존성 그룹 `group1`과 `group2`가 서로 충돌하지 않도록
# 다른 포크에서 해결되도록 요구한다.
conflicts = [
    [
        { group = "group1" },
        { group = "group2" },
    ]
]

`constraint-dependencies` {: #constraint-dependencies }¶

프로젝트의 의존성을 해결할 때 적용할 제약 조건을 설정한다.

이 제약 조건은 의존성 해결 과정에서 선택될 버전을 제한하는 데 사용된다.

패키지를 제약 조건에 포함한다고 해서 해당 패키지가 자동으로 설치되지는 않는다. 대신, 프로젝트의 직접 의존성이나 전이 의존성에서 해당 패키지를 요청해야 한다.

Note

uv lock, uv sync, uv run 명령어를 사용할 때, uv는 워크스페이스 루트의 pyproject.toml에서만 constraint-dependencies를 읽는다. 다른 워크스페이스 멤버나 uv.toml 파일에 선언된 내용은 무시한다.

기본값: []

타입: list[str]

예제 사용법:

pyproject.toml

[tool.uv]
# grpcio가 직접 의존성이나 전이 의존성에서 요청될 경우, 항상 1.65 미만의 버전을 사용하도록 제한한다.
constraint-dependencies = ["grpcio<1.65"]

`default-groups` {: #default-groups }¶

기본적으로 설치할 dependency-groups 목록을 지정한다.

기본값: ["dev"]

타입: list[str]

사용 예시:

pyproject.toml

[tool.uv]
default-groups = ["docs"]

`dev-dependencies` {: #dev-dependencies }¶

프로젝트의 개발 의존성을 정의한다.

개발 의존성은 uv run과 uv sync 명령어를 실행할 때 기본적으로 설치되지만, 프로젝트가 배포될 때는 메타데이터에 포함되지 않는다.

이 필드의 사용은 더 이상 권장하지 않는다. 대신 개발 의존성을 선언하는 표준 방식인 dependency-groups.dev 필드를 사용한다. tool.uv.dev-dependencies와 dependency-groups.dev의 내용을 결합해 dev 의존성 그룹의 최종 요구 사항을 결정한다.

기본값: []

타입: list[str]

예제 사용법:

pyproject.toml

[tool.uv]
dev-dependencies = ["ruff==0.5.0"]

`environments` {: #environments }¶

의존성을 해결할 때 고려할 지원 환경 목록이다.

기본적으로 uv는 uv lock 작업 중 가능한 모든 환경에 대해 의존성을 해결한다. 하지만 지원 환경 목록을 제한하면 성능을 개선하고 해결 공간에서 불가능한 분기를 피할 수 있다.

이 환경 목록은 --universal 플래그와 함께 uv pip compile을 실행할 때도 적용된다.

기본값: []

타입: str | list[str]

사용 예시:

pyproject.toml

[tool.uv]
# macOS에 대해서만 의존성을 해결하고, Linux나 Windows는 제외한다.
environments = ["sys_platform == 'darwin'"]

`index` {: #index }¶

의존성을 해결할 때 사용할 인덱스를 설정한다.

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

인덱스는 정의된 순서대로 고려되며, 처음 정의된 인덱스가 가장 높은 우선순위를 가진다. 또한 이 설정으로 제공된 인덱스는 index_url 또는 extra_index_url로 지정된 인덱스보다 높은 우선순위를 갖는다. uv는 특정 패키지를 포함하는 첫 번째 인덱스만 고려하며, 대체 인덱스 전략이 지정되지 않은 경우에 한한다.

인덱스가 explicit = true로 표시되면, [tool.uv.sources]를 통해 명시적으로 선택한 의존성에만 사용된다. 예를 들면:

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
explicit = true

[tool.uv.sources]
torch = { index = "pytorch" }

인덱스가 default = true로 표시되면, 우선순위 목록의 끝으로 이동하여 패키지를 해결할 때 가장 낮은 우선순위를 갖는다. 또한 인덱스를 기본값으로 표시하면 PyPI 기본 인덱스가 비활성화된다.

기본값: []

타입: dict

사용 예시:

pyproject.toml

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"

`managed` {: #managed }¶

프로젝트가 uv에 의해 관리되는지 여부를 나타낸다. false로 설정하면 uv run 명령어를 실행할 때 uv가 해당 프로젝트를 무시한다.

기본값: true

타입: bool

사용 예시:

pyproject.toml

[tool.uv]
managed = false

`override-dependencies` {: #override-dependencies }¶

프로젝트의 의존성을 해결할 때 적용할 오버라이드 설정.

오버라이드는 특정 패키지의 버전을 강제로 선택하기 위해 사용한다. 다른 패키지가 요청한 버전과 관계없이, 그리고 해당 버전 선택이 일반적으로 유효하지 않은 해결책으로 간주되더라도 오버라이드가 우선 적용된다.

제약 조건(constraints)은 구성 패키지의 요구 사항과 결합되는 추가적 성격을 지니지만, 오버라이드는 구성 패키지의 요구 사항을 완전히 대체하는 절대적 성격을 가진다.

패키지를 오버라이드에 포함한다고 해서 해당 패키지가 자동으로 설치되지는 않는다. 대신, 프로젝트의 직접 의존성이나 전이적 의존성에서 해당 패키지를 요청해야 한다.

Note

uv lock, uv sync, uv run 명령에서 uv는 워크스페이스 루트의 pyproject.toml에서만 override-dependencies를 읽어 들이며, 다른 워크스페이스 멤버나 uv.toml 파일에 선언된 내용은 무시한다.

기본값: []

타입: list[str]

예제 사용법:

pyproject.toml

[tool.uv]
# 전이적 의존성이 다른 버전을 요청하더라도 항상 Werkzeug 2.3.0을 설치.
override-dependencies = ["werkzeug==2.3.0"]

`package` {: #package }¶

프로젝트를 파이썬 패키지로 간주할지, 아니면 비패키지("가상") 프로젝트로 간주할지를 결정한다.

패키지는 가상 환경에 편집 가능한 모드로 빌드되고 설치되며, 이 경우 빌드 백엔드가 필요하다. 반면 가상 프로젝트는 빌드하거나 설치하지 않는다. 대신 가상 환경에 해당 프로젝트의 의존성만 포함된다.

패키지를 생성하려면 pyproject.toml 파일에 build-system이 존재해야 하며, 프로젝트 구조가 빌드 백엔드의 요구사항을 충족해야 한다(예: src 레이아웃).

기본값: true

타입: bool

예제 사용법:

pyproject.toml

[tool.uv]
package = false

`required-environments` {: #required-environments }¶

소스 배포가 없는 패키지에 대해 필수 플랫폼 목록을 지정한다.

패키지에 소스 배포가 없으면, 해당 패키지는 빌드된 배포판(휠)이 지원하는 플랫폼에서만 사용 가능하다. 예를 들어, 패키지가 Linux용 휠만 제공하면 macOS나 Windows에서는 설치할 수 없다.

기본적으로 uv는 각 패키지가 지정된 Python 버전과 호환되는 최소 하나의 휠을 포함하도록 요구한다. required-environments 설정을 사용하면 특정 플랫폼에 대한 휠이 포함된 해결책을 보장하거나, 해당 휠이 없을 경우 실패하도록 할 수 있다.

environments 설정은 uv가 의존성을 해결할 때 고려할 환경 집합을 제한하는 반면, required-environments는 uv가 반드시 지원해야 하는 플랫폼 집합을 확장한다.

예를 들어, environments = ["sys_platform == 'darwin'"]는 uv가 macOS만 고려하도록 제한한다(Linux와 Windows는 무시). 반면 required-environments = ["sys_platform == 'darwin'"]는 소스 배포가 없는 패키지가 macOS용 휠을 포함해야 설치 가능하도록 요구한다.

기본값: []

타입: str | list[str]

예제 사용법:

pyproject.toml

[tool.uv]
# 패키지가 macOS ARM과 x86(Intel)에서 사용 가능하도록 요구.
required-environments = [
    "sys_platform == 'darwin' and platform_machine == 'arm64'",
    "sys_platform == 'darwin' and platform_machine == 'x86_64'",
]

`sources` {: #sources }¶

의존성을 해결할 때 사용할 소스를 정의한다.

tool.uv.sources는 개발 중 추가적인 소스를 통합하여 의존성 메타데이터를 보강한다. 의존성 소스는 Git 저장소, URL, 로컬 경로 또는 대체 레지스트리가 될 수 있다.

자세한 내용은 Dependencies를 참고한다.

기본값: {}

타입: dict

예시 사용법:

pyproject.toml

[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" }
pytest = { url = "https://files.pythonhosted.org/packages/6b/77/7440a06a8ead44c7757a64362dd22df5760f9b12dc5f11b6188cd2fc27a0/pytest-8.3.3-py3-none-any.whl" }
pydantic = { path = "/path/to/pydantic", editable = true }

`workspace`¶

`exclude` {: #workspace_exclude }¶

워크스페이스 멤버에서 제외할 패키지를 지정한다. 만약 패키지가 members와 exclude 모두에 해당한다면, 해당 패키지는 제외된다.

글로브 패턴과 명시적 경로를 모두 지원한다.

글로브 문법에 대한 자세한 내용은 glob 문서를 참고한다.

기본값: []

타입: list[str]

예제 사용법:

pyproject.toml

[tool.uv.workspace]
exclude = ["member1", "path/to/member2", "libs/*"]

`members` {: #workspace_members }¶

워크스페이스 멤버로 포함할 패키지를 지정한다.

글로브 패턴과 명시적 경로를 모두 지원한다.

글로브 문법에 대한 자세한 내용은 glob 문서를 참고한다.

기본값: []

타입: list[str]

예제 사용법:

pyproject.toml

[tool.uv.workspace]
members = ["member1", "path/to/member2", "libs/*"]

설정¶

`allow-insecure-host` {: #allow-insecure-host }¶

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

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

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

기본값: []

타입: list[str]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
allow-insecure-host = ["localhost:8080"]
```

=== "uv.toml"

```toml
allow-insecure-host = ["localhost:8080"]
```

`cache-dir` {: #cache-dir }¶

캐시 디렉터리의 경로를 지정한다.

기본값은 macOS에서는 $HOME/Library/Caches/uv, Linux에서는 $XDG_CACHE_HOME/uv 또는 $HOME/.cache/uv, Windows에서는 %LOCALAPPDATA%\uv\cache로 설정된다.

기본값: None

타입: str

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv]
cache-dir = "./.uv_cache"
```

=== "uv.toml"

```toml
cache-dir = "./.uv_cache"
```

`cache-keys` {: #cache-keys }¶

프로젝트 빌드를 캐싱할 때 고려해야 할 키들이다.

캐시 키를 통해 수정 시 재빌드를 트리거해야 하는 파일이나 디렉터리를 지정할 수 있다. 기본적으로 uv는 프로젝트 디렉터리 내 pyproject.toml, setup.py, setup.cfg 파일이 수정될 때마다 프로젝트를 재빌드한다. 예를 들면:

cache-keys = [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }]

예를 들어, 프로젝트가 동적 메타데이터를 사용해 requirements.txt 파일에서 의존성을 읽는 경우, cache-keys = [{ file = "requirements.txt" }, { file = "pyproject.toml" }]를 지정해 requirements.txt 파일이 수정될 때마다 프로젝트가 재빌드되도록 할 수 있다(pyproject.toml도 함께 감시).

glob 크레이트의 문법을 따르는 글로브(glob)도 지원된다. 예를 들어, 프로젝트 디렉터리나 하위 디렉터리 내 .toml 파일이 수정될 때마다 캐시를 무효화하려면 cache-keys = [{ file = "**/*.toml" }]를 지정할 수 있다. 글로브를 사용하면 파일 시스템을 탐색해 변경된 파일이 있는지 확인해야 하므로 비용이 많이 들 수 있다.

캐시 키에는 버전 관리 정보도 포함될 수 있다. 예를 들어, 프로젝트가 setuptools_scm을 사용해 Git 커밋에서 버전을 읽는 경우, cache-keys = [{ git = { commit = true }, { file = "pyproject.toml" }]를 지정해 현재 Git 커밋 해시를 캐시 키에 포함할 수 있다(pyproject.toml도 함께). Git 태그도 cache-keys = [{ git = { commit = true, tags = true } }]를 통해 지원된다.

캐시 키에는 환경 변수도 포함될 수 있다. 예를 들어, 프로젝트가 MACOSX_DEPLOYMENT_TARGET나 다른 환경 변수에 의존해 동작을 결정하는 경우, cache-keys = [{ env = "MACOSX_DEPLOYMENT_TARGET" }]를 지정해 환경 변수가 변경될 때마다 캐시를 무효화할 수 있다.

캐시 키는 지정된 pyproject.toml에 정의된 프로젝트에만 영향을 미친다(예를 들어, 워크스페이스의 모든 멤버에 영향을 미치지 않는다). 모든 경로와 글로브는 프로젝트 디렉터리를 기준으로 해석된다.

기본값: [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }]

타입: list[dict]

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv]
cache-keys = [{ file = "pyproject.toml" }, { file = "requirements.txt" }, { git = { commit = true } }]
```

=== "uv.toml"

```toml
cache-keys = [{ file = "pyproject.toml" }, { file = "requirements.txt" }, { git = { commit = true } }]
```

`check-url` {: #check-url }¶

중복 업로드를 방지하기 위해 인덱스 URL을 확인한다.

이 옵션은 일부 파일만 업로드된 후 실패한 경우 재시도를 허용하며, 동일한 파일이 병렬로 업로드되어 발생하는 오류를 처리한다.

업로드 전에 인덱스를 확인한다. 동일한 파일이 이미 인덱스에 존재하면 해당 파일을 업로드하지 않는다. 업로드 중 오류가 발생하면 인덱스를 다시 확인하여 동일한 파일이 병렬로 두 번 업로드된 경우를 처리한다.

정확한 동작은 인덱스에 따라 다르다. PyPI에 업로드할 때는 --check-url 없이도 동일한 파일 업로드가 성공하지만, 대부분의 다른 인덱스에서는 오류가 발생한다.

인덱스는 지원되는 해시(SHA-256, SHA-384, 또는 SHA-512) 중 하나를 제공해야 한다.

기본값: None

타입: str

사용 예제:

=== "pyproject.toml"

```toml
[tool.uv]
check-url = "https://test.pypi.org/simple"
```

=== "uv.toml"

```toml
check-url = "https://test.pypi.org/simple"
```

`compile-bytecode` {: #compile-bytecode }¶

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

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

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

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
compile-bytecode = true
```

=== "uv.toml"

```toml
compile-bytecode = true
```

`concurrent-builds` {: #concurrent-builds }¶

uv가 동시에 빌드할 수 있는 소스 배포판의 최대 개수다.

기본값은 사용 가능한 CPU 코어 수로 설정된다.

기본값: None

타입: int

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv]
concurrent-builds = 4
```

=== "uv.toml"

```toml
concurrent-builds = 4
```

`concurrent-downloads` {: #concurrent-downloads }¶

uv가 동시에 수행할 수 있는 최대 다운로드 작업 수를 설정한다.

기본값: 50

타입: int

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
concurrent-downloads = 4
```

=== "uv.toml"

```toml
concurrent-downloads = 4
```

`concurrent-installs` {: #concurrent-installs }¶

패키지를 설치하고 압축 해제할 때 사용할 스레드의 수를 지정한다.

기본값은 사용 가능한 CPU 코어 수로 설정된다.

기본값: None

타입: int

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
concurrent-installs = 4
```

=== "uv.toml"

```toml
concurrent-installs = 4
```

`config-settings` {: #config-settings }¶

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

기본값: {}

타입: dict

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
config-settings = { editable_mode = "compat" }
```

=== "uv.toml"

```toml
config-settings = { editable_mode = "compat" }
```

`dependency-metadata` {: #dependency-metadata }¶

프로젝트의 직접적 또는 전이적 의존성에 대한 사전 정의된 정적 메타데이터이다. 이 메타데이터를 제공하면 리졸버가 레지스트리를 쿼리하거나 소스에서 관련 패키지를 빌드하는 대신 지정된 메타데이터를 사용한다.

메타데이터는 Metadata 2.3 표준을 준수해야 하지만, 다음 필드만 적용된다:

name: 패키지의 이름.
(선택 사항) version: 패키지의 버전. 생략하면 메타데이터가 패키지의 모든 버전에 적용된다.
(선택 사항) requires-dist: 패키지의 의존성 (예: werkzeug>=0.14).
(선택 사항) requires-python: 패키지가 요구하는 Python 버전 (예: >=3.10).
(선택 사항) provides-extras: 패키지가 제공하는 추가 기능.

기본값: []

타입: list[dict]

사용 예제:

=== "pyproject.toml"

```toml
[tool.uv]
dependency-metadata = [
    { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" },
]
```

=== "uv.toml"

```toml
dependency-metadata = [
    { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" },
]
```

`exclude-newer` {: #exclude-newer }¶

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

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

기본값: None

타입: str

사용 예제:

=== "pyproject.toml"

```toml
[tool.uv]
exclude-newer = "2006-12-02"
```

=== "uv.toml"

```toml
exclude-newer = "2006-12-02"
```

`extra-index-url` {: #extra-index-url }¶

--index-url에 추가로 사용할 패키지 인덱스의 URL을 지정한다.

PEP 503에 정의된 저장소 API를 준수하는 저장소나 동일한 형식으로 구성된 로컬 디렉토리를 인자로 받는다.

이 플래그를 통해 제공된 모든 인덱스는 index_url이나 default = true로 설정된 index보다 우선순위를 가진다. 여러 인덱스를 제공할 경우, 먼저 나온 값이 더 높은 우선순위를 갖는다.

여러 인덱스가 있을 때 uv의 해결 전략을 제어하려면 index_strategy를 참고한다.

(Deprecated: index를 대신 사용한다.)

기본값: []

타입: list[str]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
extra-index-url = ["https://download.pytorch.org/whl/cpu"]
```

=== "uv.toml"

```toml
extra-index-url = ["https://download.pytorch.org/whl/cpu"]
```

`find-links` {: #find-links }¶

레지스트리 인덱스에서 찾은 것 외에 후보 배포판을 검색할 위치를 지정한다.

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

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

기본값: []

타입: list[str]

사용 예제:

=== "pyproject.toml"

```toml
[tool.uv]
find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
```

=== "uv.toml"

```toml
find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
```

`fork-strategy` {: #fork-strategy }¶

주어진 패키지의 여러 버전을 선택할 때 사용할 전략을 정의한다. 이 전략은 Python 버전과 플랫폼 간의 호환성을 고려한다.

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

fewest 전략을 사용하면 각 패키지에 대해 선택된 버전의 수를 최소화한다. 더 넓은 범위의 Python 버전이나 플랫폼과 호환되는 이전 버전을 우선적으로 선택한다.

기본값: "requires-python"

가능한 값:

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

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv]
fork-strategy = "fewest"
```

=== "uv.toml"

```toml
fork-strategy = "fewest"
```

`index` {: #index }¶

의존성을 해결할 때 사용할 패키지 인덱스를 설정한다.

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

인덱스는 정의된 순서대로 고려되며, 처음 정의된 인덱스가 가장 높은 우선순위를 가진다. 또한 이 설정을 통해 제공된 인덱스는 index_url이나 extra_index_url로 지정된 인덱스보다 높은 우선순위를 갖는다. uv는 특정 패키지를 포함하는 첫 번째 인덱스만 고려하며, 별도의 인덱스 전략을 지정하지 않는 한 다른 인덱스는 무시한다.

인덱스가 explicit = true로 표시된 경우, [tool.uv.sources]를 통해 명시적으로 선택된 의존성에 대해서만 사용된다. 예를 들어:

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
explicit = true

[tool.uv.sources]
torch = { index = "pytorch" }

인덱스가 default = true로 표시된 경우, 우선순위 목록의 맨 끝으로 이동하여 패키지 해결 시 가장 낮은 우선순위를 갖는다. 또한 인덱스를 기본값으로 표시하면 PyPI 기본 인덱스가 비활성화된다.

기본값: "[]"

타입: dict

사용 예시:

=== "pyproject.toml"

```toml
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
```

=== "uv.toml"

```toml
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
```

`index-strategy` {: #index-strategy }¶

여러 인덱스 URL을 해결할 때 사용할 전략이다.

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

기본값: "first-index"

가능한 값:

"first-index": 주어진 패키지 이름과 일치하는 첫 번째 인덱스의 결과만 사용한다.
"unsafe-first-match": 모든 인덱스에서 각 패키지 이름을 검색하고, 첫 번째 인덱스의 버전을 모두 확인한 후 다음 인덱스로 넘어간다.
"unsafe-best-match": 모든 인덱스에서 각 패키지 이름을 검색하고, "가장 적합한" 버전을 우선한다. 패키지 버전이 여러 인덱스에 있는 경우, 첫 번째 인덱스의 항목만 확인한다.

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv]
index-strategy = "unsafe-best-match"
```

=== "uv.toml"

```toml
index-strategy = "unsafe-best-match"
```

`index-url` {: #index-url }¶

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

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

이 설정에서 제공하는 인덱스는 extra_index_url 또는 index로 지정된 인덱스보다 낮은 우선순위를 가진다.

(더 이상 사용되지 않음: index를 대신 사용한다.)

기본값: "https://pypi.org/simple"

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
index-url = "https://test.pypi.org/simple"
```

=== "uv.toml"

```toml
index-url = "https://test.pypi.org/simple"
```

`keyring-provider` {: #keyring-provider }¶

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

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

기본값: "disabled"

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
keyring-provider = "subprocess"
```

=== "uv.toml"

```toml
keyring-provider = "subprocess"
```

`link-mode` {: #link-mode }¶

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

macOS에서는 기본값이 clone(Copy-on-Write)이고, Linux와 Windows에서는 hardlink로 설정된다.

기본값: "clone" (macOS) 또는 "hardlink" (Linux, Windows)

가능한 값:

"clone": 휠에서 site-packages 디렉터리로 패키지를 복제한다(즉, Copy-on-Write 방식).
"copy": 휠에서 site-packages 디렉터리로 패키지를 복사한다.
"hardlink": 휠에서 site-packages 디렉터리로 패키지를 하드 링크한다.
"symlink": 휠에서 site-packages 디렉터리로 패키지를 심볼릭 링크한다.

사용 예제:

=== "pyproject.toml"

```toml
[tool.uv]
link-mode = "copy"
```

=== "uv.toml"

```toml
link-mode = "copy"
```

`native-tls` {: #native-tls }¶

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

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

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

기본값: false

타입: bool

사용 예제:

=== "pyproject.toml"

```toml
[tool.uv]
native-tls = true
```

=== "uv.toml"

```toml
native-tls = true
```

`no-binary` {: #no-binary }¶

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

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

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
no-binary = true
```

=== "uv.toml"

```toml
no-binary = true
```

`no-binary-package` {: #no-binary-package }¶

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

기본값: []

타입: list[str]

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv]
no-binary-package = ["ruff"]
```

=== "uv.toml"

```toml
no-binary-package = ["ruff"]
```

`no-build` {: #no-build }¶

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

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

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
no-build = true
```

=== "uv.toml"

```toml
no-build = true
```

`no-build-isolation` {: #no-build-isolation }¶

소스 배포를 빌드할 때 격리 기능을 비활성화한다.

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

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
no-build-isolation = true
```

=== "uv.toml"

```toml
no-build-isolation = true
```

`no-build-isolation-package` {: #no-build-isolation-package }¶

특정 패키지의 소스 배포를 빌드할 때 격리 기능을 비활성화한다.

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

기본값: []

타입: list[str]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
no-build-isolation-package = ["package1", "package2"]
```

=== "uv.toml"

```toml
no-build-isolation-package = ["package1", "package2"]
```

`no-build-package` {: #no-build-package }¶

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

기본값: []

타입: list[str]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
no-build-package = ["ruff"]
```

=== "uv.toml"

```toml
no-build-package = ["ruff"]
```

`no-cache` {: #no-cache }¶

캐시에서 읽거나 쓰는 것을 피하고, 작업 기간 동안 임시 디렉터리를 사용한다.

기본값: false

타입: bool

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv]
no-cache = true
```

=== "uv.toml"

```toml
no-cache = true
```

`no-index` {: #no-index }¶

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

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
no-index = true
```

=== "uv.toml"

```toml
no-index = true
```

`no-sources` {: #no-sources }¶

의존성을 해결할 때 tool.uv.sources 테이블을 무시한다. 이 설정은 로컬이나 Git 소스를 사용하는 대신, 표준을 준수하고 공개 가능한 패키지 메타데이터를 기준으로 잠금을 수행하는 데 사용된다.

기본값: false

타입: bool

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv]
no-sources = true
```

=== "uv.toml"

```toml
no-sources = true
```

`offline` {: #offline }¶

네트워크 접근을 비활성화하고, 로컬 캐시 데이터와 로컬에서 사용 가능한 파일만 의존한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
offline = true
```

=== "uv.toml"

```toml
offline = true
```

`prerelease` {: #prerelease }¶

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

기본적으로 uv는 사전 릴리스만 제공하는 패키지와, 명시적으로 사전 릴리스 마커가 포함된 첫 번째 파티 요구 사항을 허용한다(if-necessary-or-explicit).

기본값: "if-necessary-or-explicit"

가능한 값:

"disallow": 모든 사전 릴리스 버전을 허용하지 않음
"allow": 모든 사전 릴리스 버전을 허용
"if-necessary": 패키지의 모든 버전이 사전 릴리스인 경우에만 허용
"explicit": 버전 요구 사항에 명시적 사전 릴리스 마커가 있는 첫 번째 파티 패키지만 허용
"if-necessary-or-explicit": 패키지의 모든 버전이 사전 릴리스이거나, 버전 요구 사항에 명시적 사전 릴리스 마커가 있는 경우 허용

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
prerelease = "allow"
```

=== "uv.toml"

```toml
prerelease = "allow"
```

`preview` {: #preview }¶

실험적이고 미리 보기 기능을 활성화할지 여부를 결정한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
preview = true
```

=== "uv.toml"

```toml
preview = true
```

`publish-url` {: #publish-url }¶

파이썬 패키지 인덱스에 패키지를 배포하기 위한 URL이다. 기본값은 https://upload.pypi.org/legacy/이다.

기본값: "https://upload.pypi.org/legacy/"

타입: str

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv]
publish-url = "https://test.pypi.org/legacy/"
```

=== "uv.toml"

```toml
publish-url = "https://test.pypi.org/legacy/"
```

`pypy-install-mirror` {: #pypy-install-mirror }¶

PyPy 설치 파일을 다운로드할 때 사용할 미러 URL을 지정한다.

기본적으로 PyPy 설치 파일은 downloads.python.org에서 다운로드된다. 이 변수를 설정하면 다른 소스에서 PyPy 설치 파일을 가져올 수 있다. 제공된 URL은 https://downloads.python.org/pypy를 대체한다. 예를 들어, https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2와 같은 URL에서 https://downloads.python.org/pypy 부분이 변경된다.

file:// URL 스키마를 사용하면 로컬 디렉터리에서 배포 파일을 읽을 수 있다.

기본값: None

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
pypy-install-mirror = "https://downloads.python.org/pypy"
```

=== "uv.toml"

```toml
pypy-install-mirror = "https://downloads.python.org/pypy"
```

`python-downloads` {: #python-downloads }¶

파이썬 다운로드를 허용할지 여부를 설정한다.

기본값: "automatic"

가능한 값:

"automatic": 필요할 때 관리되는 파이썬 설치를 자동으로 다운로드
"manual": 관리되는 파이썬 설치를 자동으로 다운로드하지 않음; 명시적인 설치 필요
"never": 파이썬 다운로드를 전혀 허용하지 않음

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
python-downloads = "manual"
```

=== "uv.toml"

```toml
python-downloads = "manual"
```

`python-install-mirror` {: #python-install-mirror }¶

관리되는 Python 설치 파일을 다운로드하기 위한 미러 URL.

기본적으로 관리되는 Python 설치 파일은 python-build-standalone에서 다운로드된다. 이 변수를 설정하면 Python 설치 파일을 다른 소스에서 다운로드할 수 있다. 제공된 URL은 https://github.com/astral-sh/python-build-standalone/releases/download를 대체한다. 예를 들어, https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz와 같은 URL에서 사용된다.

file:// URL 스키마를 사용하면 로컬 디렉토리에서 배포판을 읽을 수 있다.

기본값: None

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
python-install-mirror = "https://github.com/astral-sh/python-build-standalone/releases/download"
```

=== "uv.toml"

```toml
python-install-mirror = "https://github.com/astral-sh/python-build-standalone/releases/download"
```

`python-preference` {: #python-preference }¶

시스템에 이미 설치된 Python을 사용할지, 아니면 uv가 다운로드하여 설치한 Python을 사용할지 설정한다.

기본값: "managed"

가능한 값:

"only-managed": 시스템 Python을 사용하지 않고, uv가 관리하는 Python만 사용한다.
"managed": 시스템 Python보다 uv가 관리하는 Python을 우선적으로 사용한다.
"system": uv가 관리하는 Python보다 시스템 Python을 우선적으로 사용한다.
"only-system": uv가 관리하는 Python을 사용하지 않고, 시스템 Python만 사용한다.

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
python-preference = "managed"
```

=== "uv.toml"

```toml
python-preference = "managed"
```

`reinstall` {: #reinstall }¶

이미 설치된 패키지 여부와 상관없이 모든 패키지를 재설치한다. refresh를 암시한다.

기본값: false

타입: bool

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv]
reinstall = true
```

=== "uv.toml"

```toml
reinstall = true
```

`reinstall-package` {: #reinstall-package }¶

특정 패키지를 이미 설치했는지 여부와 상관없이 재설치한다. 이 옵션은 refresh-package를 암시한다.

기본값: []

타입: list[str]

사용 예제:

=== "pyproject.toml"

```toml
[tool.uv]
reinstall-package = ["ruff"]
```

=== "uv.toml"

```toml
reinstall-package = ["ruff"]
```

`required-version` {: #required-version }¶

uv 버전에 대한 요구사항을 강제한다.

런타임에 uv 버전이 요구사항을 충족하지 않으면 uv는 에러와 함께 종료된다.

==0.5.0 또는 >=0.5.0과 같은 PEP 440 스펙을 받는다.

기본값: null

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
required-version = ">=0.5.0"
```

=== "uv.toml"

```toml
required-version = ">=0.5.0"
```

`resolution` {: #resolution }¶

주어진 패키지 요구사항에 대해 호환 가능한 여러 버전 중 하나를 선택할 때 사용하는 전략이다.

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

기본값: "highest"

가능한 값:

"highest": 각 패키지의 가장 높은 호환 버전을 선택한다.
"lowest": 각 패키지의 가장 낮은 호환 버전을 선택한다.
"lowest-direct": 직접 의존성의 가장 낮은 호환 버전을 선택하고, 전이 의존성의 가장 높은 호환 버전을 선택한다.

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv]
resolution = "lowest-direct"
```

=== "uv.toml"

```toml
resolution = "lowest-direct"
```

`trusted-publishing` {: #trusted-publishing }¶

GitHub Actions를 통해 신뢰할 수 있는 퍼블리싱을 설정한다.

기본적으로 uv는 GitHub Actions에서 실행될 때 신뢰할 수 있는 퍼블리싱을 확인한다. 하지만 설정이 되어 있지 않거나 워크플로에 충분한 권한이 없는 경우(예: 포크에서 온 풀 리퀘스트) 이를 무시한다.

기본값: automatic

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
trusted-publishing = "always"
```

=== "uv.toml"

```toml
trusted-publishing = "always"
```

`upgrade` {: #upgrade }¶

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

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
upgrade = true
```

=== "uv.toml"

```toml
upgrade = true
```

`upgrade-package` {: #upgrade-package }¶

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

단독 패키지 이름(ruff)과 버전 지정자(ruff<0.5.0)를 모두 지원한다.

기본값: []

타입: list[str]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv]
upgrade-package = ["ruff"]
```

=== "uv.toml"

```toml
upgrade-package = ["ruff"]
```

`pip`¶

uv pip 커맨드라인 인터페이스에 특화된 설정값들이다.

이 값들은 uv pip 네임스페이스 외부에서 실행되는 명령어(예: uv lock, uvx)에서는 무시된다.

`all-extras` {: #pip_all-extras }¶

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

pyproject.toml, setup.py, setup.cfg 소스에만 적용된다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
all-extras = true
```

=== "uv.toml"

```toml
[pip]
all-extras = true
```

`allow-empty-requirements` {: #pip_allow-empty-requirements }¶

uv pip sync 명령어를 빈 요구사항으로 실행할 수 있게 한다. 이 경우 환경에 설치된 모든 패키지를 제거한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
allow-empty-requirements = true
```

=== "uv.toml"

```toml
[pip]
allow-empty-requirements = true
```

`annotation-style` {: #pip_annotation-style }¶

출력 파일에 포함된 주석의 스타일을 지정한다. 각 패키지의 출처를 표시하는 데 사용한다.

기본값: "split"

가능한 값:

"line": 주석을 쉼표로 구분된 한 줄로 렌더링
"split": 각 주석을 별도의 줄로 렌더링

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
annotation-style = "line"
```

=== "uv.toml"

```toml
[pip]
annotation-style = "line"
```

`break-system-packages` {: #pip_break-system-packages }¶

uv가 EXTERNALLY-MANAGED Python 설치를 수정할 수 있도록 허용한다.

경고: --break-system-packages는 외부 패키지 관리자(예: apt)가 관리하는 Python 설치 환경에서, 특히 지속적 통합(CI) 환경에서 사용하기 위한 옵션이다. 이 옵션은 주의해서 사용해야 한다. 해당 Python 설치 환경은 다른 패키지 관리자(예: uv 또는 pip)에 의한 수정을 명시적으로 권장하지 않기 때문이다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
break-system-packages = true
```

=== "uv.toml"

```toml
[pip]
break-system-packages = true
```

`compile-bytecode` {: #pip_compile-bytecode }¶

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

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

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

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
compile-bytecode = true
```

=== "uv.toml"

```toml
[pip]
compile-bytecode = true
```

`config-settings` {: #pip_config-settings }¶

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

기본값: {}

타입: dict

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
config-settings = { editable_mode = "compat" }
```

=== "uv.toml"

```toml
[pip]
config-settings = { editable_mode = "compat" }
```

`custom-compile-command` {: #pip_custom-compile-command }¶

uv pip compile로 생성된 출력 파일의 상단에 포함할 헤더 주석.

uv pip compile을 래핑하는 커스텀 빌드 스크립트와 커맨드를 반영하는 데 사용한다.

기본값: None

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
custom-compile-command = "./custom-uv-compile.sh"
```

=== "uv.toml"

```toml
[pip]
custom-compile-command = "./custom-uv-compile.sh"
```

`dependency-metadata` {: #pip_dependency-metadata }¶

프로젝트의 직접적 또는 간접적 의존성에 대한 사전 정의된 정적 메타데이터를 제공한다. 이 메타데이터를 제공하면 리졸버가 레지스트리를 조회하거나 소스에서 관련 패키지를 빌드하는 대신 지정된 메타데이터를 사용할 수 있다.

메타데이터는 Metadata 2.3 표준을 준수해야 하지만, 다음 필드만 인식된다:

name: 패키지의 이름
(선택 사항) version: 패키지의 버전. 생략하면 모든 버전의 패키지에 메타데이터가 적용된다.
(선택 사항) requires-dist: 패키지의 의존성 (예: werkzeug>=0.14)
(선택 사항) requires-python: 패키지가 요구하는 Python 버전 (예: >=3.10)
(선택 사항) provides-extras: 패키지가 제공하는 추가 기능

기본값: []

타입: list[dict]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
dependency-metadata = [
    { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" },
]
```

=== "uv.toml"

```toml
[pip]
dependency-metadata = [
    { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" },
]
```

`emit-build-options` {: #pip_emit-build-options }¶

uv pip compile 명령으로 생성된 출력 파일에 --no-binary와 --only-binary 항목을 포함한다.

기본값: false

타입: bool

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv.pip]
emit-build-options = true
```

=== "uv.toml"

```toml
[pip]
emit-build-options = true
```

`emit-find-links` {: #pip_emit-find-links }¶

uv pip compile로 생성된 출력 파일에 --find-links 항목을 포함한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
emit-find-links = true
```

=== "uv.toml"

```toml
[pip]
emit-find-links = true
```

`emit-index-annotation` {: #pip_emit-index-annotation }¶

각 패키지를 해결하는 데 사용된 인덱스를 나타내는 주석을 포함한다 (예: # from https://pypi.org/simple).

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
emit-index-annotation = true
```

=== "uv.toml"

```toml
[pip]
emit-index-annotation = true
```

`emit-index-url` {: #pip_emit-index-url }¶

uv pip compile 명령으로 생성된 출력 파일에 --index-url과 --extra-index-url 항목을 포함한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
emit-index-url = true
```

=== "uv.toml"

```toml
[pip]
emit-index-url = true
```

`emit-marker-expression` {: #pip_emit-marker-expression }¶

고정된 의존성 집합이 유효한 조건을 나타내는 마커 문자열을 내보낼지 여부를 결정한다.

마커 표현식이 거짓일 때도 고정된 의존성이 유효할 수 있지만, 표현식이 참일 때는 요구사항이 정확하다는 것을 보장한다.

기본값: false

타입: bool

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv.pip]
emit-marker-expression = true
```

=== "uv.toml"

```toml
[pip]
emit-marker-expression = true
```

`exclude-newer` {: #pip_exclude-newer }¶

특정 시점 이전에 업로드된 패키지만 후보로 제한한다.

RFC 3339 형식의 상위 집합을 허용한다 (예: 2006-12-02T02:07:43Z). 타임존에 상관없이 일관된 동작을 보장하기 위해 전체 타임스탬프가 필요하다.

기본값: None

타입: str

사용 예제:

=== "pyproject.toml"

```toml
[tool.uv.pip]
exclude-newer = "2006-12-02T02:07:43Z"
```

=== "uv.toml"

```toml
[pip]
exclude-newer = "2006-12-02T02:07:43Z"
```

`extra` {: #pip_extra }¶

지정된 extra에서 선택적 의존성을 포함한다. 여러 번 제공할 수 있다.

pyproject.toml, setup.py, setup.cfg 소스에만 적용된다.

기본값: []

타입: list[str]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
extra = ["dev", "docs"]
```

=== "uv.toml"

```toml
[pip]
extra = ["dev", "docs"]
```

`extra-index-url` {: #pip_extra-index-url }¶

--index-url에 추가로 사용할 패키지 인덱스의 URL을 지정한다.

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

이 플래그를 통해 제공된 모든 인덱스는 index_url로 지정된 인덱스보다 우선순위를 가진다. 여러 인덱스가 제공되면, 먼저 입력된 값이 더 높은 우선순위를 갖는다.

여러 인덱스가 있을 때 uv의 해결 전략을 제어하려면 index_strategy를 참고한다.

기본값: []

타입: list[str]

예제:

=== "pyproject.toml"

```toml
[tool.uv.pip]
extra-index-url = ["https://download.pytorch.org/whl/cpu"]
```

=== "uv.toml"

```toml
[pip]
extra-index-url = ["https://download.pytorch.org/whl/cpu"]
```

`find-links` {: #pip_find-links }¶

레지스트리 인덱스에서 찾은 것 외에 후보 배포판을 검색할 위치를 지정한다.

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

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

기본값: []

타입: list[str]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
```

=== "uv.toml"

```toml
[pip]
find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
```

`fork-strategy` {: #pip_fork-strategy }¶

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

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

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

기본값: "requires-python"

가능한 값:

"fewest": 각 패키지에 대해 선택된 버전 수를 최소화하도록 최적화한다. 지원되는 Python 버전이나 플랫폼 범위가 더 넓은 구형 버전을 선호할 수 있다.
"requires-python": 지원되는 Python 버전마다 각 패키지의 최신 지원 버전을 선택하도록 최적화한다.

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv.pip]
fork-strategy = "fewest"
```

=== "uv.toml"

```toml
[pip]
fork-strategy = "fewest"
```

`generate-hashes` {: #pip_generate-hashes }¶

출력 파일에 배포본 해시를 포함한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
generate-hashes = true
```

=== "uv.toml"

```toml
[pip]
generate-hashes = true
```

`index-strategy` {: #pip_index-strategy }¶

여러 인덱스 URL을 해결할 때 사용할 전략을 설정한다.

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

기본값: "first-index"

가능한 값:

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

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv.pip]
index-strategy = "unsafe-best-match"
```

=== "uv.toml"

```toml
[pip]
index-strategy = "unsafe-best-match"
```

`index-url` {: #pip_index-url }¶

파이썬 패키지 인덱스의 URL (기본값: https://pypi.org/simple).

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

이 설정에서 제공하는 인덱스는 extra_index_url을 통해 지정된 모든 인덱스보다 우선순위가 낮다.

기본값: "https://pypi.org/simple"

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
index-url = "https://test.pypi.org/simple"
```

=== "uv.toml"

```toml
[pip]
index-url = "https://test.pypi.org/simple"
```

`keyring-provider` {: #pip_keyring-provider }¶

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

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

기본값: disabled

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
keyring-provider = "subprocess"
```

=== "uv.toml"

```toml
[pip]
keyring-provider = "subprocess"
```

`link-mode` {: #pip_link-mode }¶

패키지를 전역 캐시에서 설치할 때 사용할 방법을 설정한다.

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

기본값: "clone" (macOS) 또는 "hardlink" (Linux, Windows)

가능한 값:

"clone": 휠에서 site-packages 디렉토리로 패키지를 클론(즉, Copy-on-Write 방식) 한다
"copy": 휠에서 site-packages 디렉토리로 패키지를 복사한다
"hardlink": 휠에서 site-packages 디렉토리로 패키지를 하드 링크한다
"symlink": 휠에서 site-packages 디렉토리로 패키지를 심볼릭 링크한다

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv.pip]
link-mode = "copy"
```

=== "uv.toml"

```toml
[pip]
link-mode = "copy"
```

`no-annotate` {: #pip_no-annotate }¶

uv pip compile로 생성된 출력 파일에서 각 패키지의 출처를 나타내는 주석 어노테이션을 제외한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
no-annotate = true
```

=== "uv.toml"

```toml
[pip]
no-annotate = true
```

`no-binary` {: #pip_no_binary }¶

사전 빌드된 휠을 설치하지 않는다.

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

여러 패키지를 지정할 수 있다. 모든 패키지에 대해 바이너리 설치를 비활성화하려면 :all:을 사용한다. 이전에 지정한 패키지를 지우려면 :none:을 사용한다.

기본값: []

타입: list[str]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
no-binary = ["ruff"]
```

=== "uv.toml"

```toml
[pip]
no-binary = ["ruff"]
```

`no-build` {: #pip_no-build }¶

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

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

--only-binary :all:의 별칭이다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
no-build = true
```

=== "uv.toml"

```toml
[pip]
no-build = true
```

`no-build-isolation` {: #pip_no-build-isolation }¶

소스 배포를 빌드할 때 격리 기능을 비활성화한다.

PEP 518에 명시된 빌드 종속성이 이미 설치되어 있다고 가정한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
no-build-isolation = true
```

=== "uv.toml"

```toml
[pip]
no-build-isolation = true
```

`no-build-isolation-package` {: #pip_no-build-isolation-package }¶

특정 패키지의 소스 배포를 빌드할 때 격리 기능을 비활성화한다.

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

기본값: []

타입: list[str]

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv.pip]
no-build-isolation-package = ["package1", "package2"]
```

=== "uv.toml"

```toml
[pip]
no-build-isolation-package = ["package1", "package2"]
```

`no-deps` {: #pip_no_deps }¶

패키지 의존성을 무시하고, 커맨드라인에 명시적으로 나열된 패키지만 최종 요구사항 파일에 추가한다.

기본값: false

타입: bool

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv.pip]
no-deps = true
```

=== "uv.toml"

```toml
[pip]
no-deps = true
```

`no-emit-package` {: #pip_no-emit-package }¶

출력 결과에서 제외할 패키지를 지정한다. 해당 패키지의 의존성은 여전히 결과에 포함된다. pip-compile의 --unsafe-package 옵션과 동일한 기능이다.

기본값: []

타입: list[str]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
no-emit-package = ["ruff"]
```

=== "uv.toml"

```toml
[pip]
no-emit-package = ["ruff"]
```

`no-extra` {: #pip_no-extra }¶

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

기본값: []

타입: list[str]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
all-extras = true
no-extra = ["dev", "docs"]
```

=== "uv.toml"

```toml
[pip]
all-extras = true
no-extra = ["dev", "docs"]
```

`no-header` {: #pip_no-header }¶

uv pip compile 명령으로 생성된 출력 파일 상단의 주석 헤더를 제외한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
no-header = true
```

=== "uv.toml"

```toml
[pip]
no-header = true
```

`no-index` {: #pip_no-index }¶

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

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
no-index = true
```

=== "uv.toml"

```toml
[pip]
no-index = true
```

`no-sources` {: #pip_no-sources }¶

의존성을 해결할 때 tool.uv.sources 테이블을 무시한다. 로컬이나 Git 소스 대신 표준을 준수하고 공개 가능한 패키지 메타데이터를 기준으로 잠금을 수행한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
no-sources = true
```

=== "uv.toml"

```toml
[pip]
no-sources = true
```

`no-strip-extras` {: #pip_no-strip-extras }¶

출력 파일에 extras를 포함한다.

기본적으로 uv는 extras를 제거한다. extras로 포함된 패키지들은 이미 출력 파일의 의존성으로 직접 포함되기 때문이다. 또한 --no-strip-extras로 생성된 출력 파일은 install 및 sync 명령에서 제약 조건 파일로 사용할 수 없다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
no-strip-extras = true
```

=== "uv.toml"

```toml
[pip]
no-strip-extras = true
```

`no-strip-markers` {: #pip_no-strip-markers }¶

uv pip compile로 생성된 출력 파일에 환경 마커를 포함한다.

기본적으로 uv는 환경 마커를 제거한다. compile로 생성된 결과는 타겟 환경에서만 정확성을 보장하기 때문이다.

기본값: false

타입: bool

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv.pip]
no-strip-markers = true
```

=== "uv.toml"

```toml
[pip]
no-strip-markers = true
```

`only-binary` {: #pip_only-binary }¶

소스 배포를 빌드하지 않고 사전 빌드된 휠만 사용한다.

이 옵션을 활성화하면 주어진 패키지에서 코드를 실행하지 않는다. 이미 빌드된 소스 배포의 캐시된 휠은 재사용하지만, 배포를 빌드해야 하는 작업은 오류와 함께 종료된다.

여러 패키지를 지정할 수 있다. 모든 패키지에 대해 바이너리를 비활성화하려면 :all:을 사용한다. 이전에 지정한 패키지를 지우려면 :none:을 사용한다.

기본값: []

타입: list[str]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
only-binary = ["ruff"]
```

=== "uv.toml"

```toml
[pip]
only-binary = ["ruff"]
```

`output-file` {: #pip_output-file }¶

uv pip compile로 생성된 요구 사항을 지정된 requirements.txt 파일에 작성한다.

파일이 이미 존재하는 경우, --upgrade 옵션을 지정하지 않으면 기존 버전을 우선적으로 사용해 의존성을 해결한다.

기본값: None

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
output-file = "requirements.txt"
```

=== "uv.toml"

```toml
[pip]
output-file = "requirements.txt"
```

`prefix` {: #pip_prefix }¶

가상 환경이 특정 위치에 있는 것처럼, 지정된 디렉토리 아래의 lib, bin 및 기타 최상위 폴더에 패키지를 설치한다.

일반적으로 --python을 사용해 대체 환경에 설치하는 것을 권장한다. --prefix를 통해 설치된 스크립트와 기타 아티팩트는 --prefix 디렉토리에 추가된 인터프리터가 아닌 설치 중인 인터프리터를 참조하기 때문에 이식성이 떨어진다.

기본값: None

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
prefix = "./prefix"
```

=== "uv.toml"

```toml
[pip]
prefix = "./prefix"
```

`prerelease` {: #pip_prerelease }¶

사전 릴리스 버전을 처리할 때 사용하는 전략이다.

기본적으로 uv는 사전 릴리스만 제공하는 패키지와, 버전 요구사항에 명시적으로 사전 릴리스 마커가 포함된 첫 번째 파티 요구사항을 허용한다(if-necessary-or-explicit).

기본값: "if-necessary-or-explicit"

가능한 값:

"disallow": 모든 사전 릴리스 버전을 허용하지 않는다
"allow": 모든 사전 릴리스 버전을 허용한다
"if-necessary": 패키지의 모든 버전이 사전 릴리스인 경우에만 사전 릴리스 버전을 허용한다
"explicit": 버전 요구사항에 명시적으로 사전 릴리스 마커가 포함된 첫 번째 파티 패키지의 사전 릴리스 버전을 허용한다
"if-necessary-or-explicit": 패키지의 모든 버전이 사전 릴리스이거나, 버전 요구사항에 명시적으로 사전 릴리스 마커가 포함된 경우 사전 릴리스 버전을 허용한다

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
prerelease = "allow"
```

=== "uv.toml"

```toml
[pip]
prerelease = "allow"
```

`python` {: #pip_python }¶

패키지를 설치할 파이썬 인터프리터를 지정한다.

기본적으로 uv는 현재 작업 디렉토리 또는 상위 디렉토리에 있는 가상 환경에 패키지를 설치한다. --python 옵션을 사용하면 다른 인터프리터를 지정할 수 있으며, 이는 지속적 통합(CI) 환경이나 자동화된 워크플로우에서 유용하다.

지원되는 형식: - 3.10은 윈도우에서 레지스트리에 설치된 파이썬 3.10을 찾는다 (py --list-paths 참조). 리눅스와 macOS에서는 python3.10을 찾는다. - python3.10 또는 python.exe는 PATH에서 해당 이름의 바이너리를 찾는다. - /home/ferris/.local/bin/python3.10은 주어진 경로에 정확히 위치한 파이썬을 사용한다.

기본값: None

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
python = "3.10"
```

=== "uv.toml"

```toml
[pip]
python = "3.10"
```

`python-platform` {: #pip_python-platform }¶

요구사항이 해결되어야 하는 플랫폼을 지정한다.

대상 플랫폼을 CPU, 벤더, 운영체제 이름으로 설명하는 "target triple" 문자열로 표현한다. 예를 들어 x86_64-unknown-linux-gnu 또는 aarch64-apple-darwin과 같은 형식이다.

기본값: None

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
python-platform = "x86_64-unknown-linux-gnu"
```

=== "uv.toml"

```toml
[pip]
python-platform = "x86_64-unknown-linux-gnu"
```

`python-version` {: #pip_python-version }¶

해결된 요구사항이 지원해야 하는 최소 Python 버전을 지정한다 (예: 3.8 또는 3.8.17).

패치 버전을 생략하면 최소 패치 버전으로 간주한다. 예를 들어, 3.8은 3.8.0으로 매핑된다.

기본값: None

타입: str

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv.pip]
python-version = "3.8"
```

=== "uv.toml"

```toml
[pip]
python-version = "3.8"
```

`reinstall` {: #pip_reinstall }¶

이미 설치된 패키지 여부와 상관없이 모든 패키지를 재설치한다. 이 옵션은 refresh를 암시한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
reinstall = true
```

=== "uv.toml"

```toml
[pip]
reinstall = true
```

`reinstall-package` {: #pip_reinstall-package }¶

이미 설치된 여부와 상관없이 특정 패키지를 재설치한다. 이 설정은 refresh-package를 암시한다.

기본값: []

타입: list[str]

사용 예제:

=== "pyproject.toml"

```toml
[tool.uv.pip]
reinstall-package = ["ruff"]
```

=== "uv.toml"

```toml
[pip]
reinstall-package = ["ruff"]
```

`require-hashes` {: #pip_require-hashes }¶

각 요구사항에 대해 일치하는 해시를 요구한다.

해시 검증 모드는 전체 적용 방식이다. 이 기능을 활성화하면 모든 요구사항에 해당하는 해시 또는 해시 집합을 제공해야 한다. 또한, 이 모드를 활성화하면 모든 요구사항은 정확한 버전으로 고정하거나(==1.0.0), 직접 URL로 지정해야 한다.

해시 검증 모드는 몇 가지 추가 제약을 도입한다:

Git 의존성은 지원하지 않는다.
수정 가능한 설치(editable installs)는 지원하지 않는다.
디렉토리가 아닌 특정 휠(.whl) 또는 소스 아카이브(.zip, .tar.gz)를 가리키는 경우를 제외하고, 로컬 의존성은 지원하지 않는다.

기본값: false

타입: bool

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv.pip]
require-hashes = true
```

=== "uv.toml"

```toml
[pip]
require-hashes = true
```

`resolution` {: #pip_resolution }¶

주어진 패키지 요구 사항에 대해 호환 가능한 버전들 중에서 선택할 때 사용할 전략.

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

기본값: "highest"

가능한 값:

"highest": 각 패키지의 최고 호환 버전을 선택
"lowest": 각 패키지의 최저 호환 버전을 선택
"lowest-direct": 직접 의존성의 최저 호환 버전을 선택하고, 전이적 의존성의 최고 호환 버전을 선택

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv.pip]
resolution = "lowest-direct"
```

=== "uv.toml"

```toml
[pip]
resolution = "lowest-direct"
```

`strict` {: #pip_strict }¶

파이썬 환경을 검증하여 누락된 종속성이 있는 패키지와 기타 문제를 감지한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
strict = true
```

=== "uv.toml"

```toml
[pip]
strict = true
```

`system` {: #pip_system }¶

패키지를 시스템 Python 환경에 설치한다.

기본적으로 uv는 현재 작업 디렉토리나 상위 디렉토리에 있는 가상 환경에 패키지를 설치한다. --system 옵션을 사용하면 시스템 PATH에서 첫 번째로 발견된 Python을 사용한다.

경고: --system은 지속적 통합(CI) 환경에서 사용하기 위한 목적으로 설계되었으며, 시스템 Python 설치를 변경할 수 있으므로 주의해서 사용해야 한다.

기본값: false

타입: bool

예제 사용법:

=== "pyproject.toml"

```toml
[tool.uv.pip]
system = true
```

=== "uv.toml"

```toml
[pip]
system = true
```

`target` {: #pip_target }¶

패키지를 가상 환경이나 시스템 Python 환경 대신 지정된 디렉토리에 설치한다. 패키지는 해당 디렉토리의 최상위 레벨에 설치된다.

기본값: None

타입: str

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
target = "./target"
```

=== "uv.toml"

```toml
[pip]
target = "./target"
```

`universal` {: #pip_universal }¶

모든 운영체제, 아키텍처, 파이썬 구현체와 호환되는 단일 requirements.txt 출력 파일을 생성하기 위해 범용 해결 방식을 수행한다.

범용 모드에서는 현재 파이썬 버전(또는 사용자가 제공한 --python-version)을 하한선으로 간주한다. 예를 들어, --universal --python-version 3.7은 파이썬 3.7 이상 버전에 대해 범용 해결 방식을 생성한다.

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
universal = true
```

=== "uv.toml"

```toml
[pip]
universal = true
```

`upgrade` {: #pip_upgrade }¶

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

기본값: false

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
upgrade = true
```

=== "uv.toml"

```toml
[pip]
upgrade = true
```

`upgrade-package` {: #pip_upgrade-package }¶

기존 출력 파일에 고정된 버전을 무시하고 특정 패키지를 업그레이드할 수 있도록 허용한다.

단독 패키지 이름(ruff)과 버전 지정자(ruff<0.5.0) 모두를 인자로 받는다.

기본값: []

타입: list[str]

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
upgrade-package = ["ruff"]
```

=== "uv.toml"

```toml
[pip]
upgrade-package = ["ruff"]
```

`verify-hashes` {: #pip_verify-hashes }¶

요구사항 파일에 제공된 해시 값을 검증한다.

--require-hashes와 달리, --verify-hashes는 모든 요구사항에 해시가 있어야 할 필요는 없다. 대신, 해시가 포함된 요구사항에 대해서만 검증을 수행한다.

기본값: true

타입: bool

사용 예시:

=== "pyproject.toml"

```toml
[tool.uv.pip]
verify-hashes = true
```

=== "uv.toml"

```toml
[pip]
verify-hashes = true
```

Settings

프로젝트 메타데이터¶

build-constraint-dependencies {: #build-constraint-dependencies }¶

conflicts {: #conflicts }¶

constraint-dependencies {: #constraint-dependencies }¶

default-groups {: #default-groups }¶

dev-dependencies {: #dev-dependencies }¶

environments {: #environments }¶

index {: #index }¶

managed {: #managed }¶

override-dependencies {: #override-dependencies }¶

package {: #package }¶

required-environments {: #required-environments }¶

sources {: #sources }¶

workspace¶

exclude {: #workspace_exclude }¶

members {: #workspace_members }¶

설정¶

allow-insecure-host {: #allow-insecure-host }¶

cache-dir {: #cache-dir }¶

cache-keys {: #cache-keys }¶

check-url {: #check-url }¶

compile-bytecode {: #compile-bytecode }¶

concurrent-builds {: #concurrent-builds }¶

concurrent-downloads {: #concurrent-downloads }¶

concurrent-installs {: #concurrent-installs }¶

config-settings {: #config-settings }¶

dependency-metadata {: #dependency-metadata }¶

exclude-newer {: #exclude-newer }¶

extra-index-url {: #extra-index-url }¶

find-links {: #find-links }¶

fork-strategy {: #fork-strategy }¶

index {: #index }¶

index-strategy {: #index-strategy }¶

index-url {: #index-url }¶

keyring-provider {: #keyring-provider }¶

link-mode {: #link-mode }¶

native-tls {: #native-tls }¶

no-binary {: #no-binary }¶

no-binary-package {: #no-binary-package }¶

no-build {: #no-build }¶

no-build-isolation {: #no-build-isolation }¶

no-build-isolation-package {: #no-build-isolation-package }¶

no-build-package {: #no-build-package }¶

no-cache {: #no-cache }¶

no-index {: #no-index }¶

no-sources {: #no-sources }¶

offline {: #offline }¶

prerelease {: #prerelease }¶

preview {: #preview }¶

publish-url {: #publish-url }¶

pypy-install-mirror {: #pypy-install-mirror }¶

python-downloads {: #python-downloads }¶

python-install-mirror {: #python-install-mirror }¶

python-preference {: #python-preference }¶

reinstall {: #reinstall }¶

reinstall-package {: #reinstall-package }¶

required-version {: #required-version }¶

resolution {: #resolution }¶

trusted-publishing {: #trusted-publishing }¶

upgrade {: #upgrade }¶

upgrade-package {: #upgrade-package }¶

pip¶

all-extras {: #pip_all-extras }¶

allow-empty-requirements {: #pip_allow-empty-requirements }¶

annotation-style {: #pip_annotation-style }¶

break-system-packages {: #pip_break-system-packages }¶

compile-bytecode {: #pip_compile-bytecode }¶

config-settings {: #pip_config-settings }¶

custom-compile-command {: #pip_custom-compile-command }¶

dependency-metadata {: #pip_dependency-metadata }¶

emit-build-options {: #pip_emit-build-options }¶

emit-find-links {: #pip_emit-find-links }¶

emit-index-annotation {: #pip_emit-index-annotation }¶

emit-index-url {: #pip_emit-index-url }¶

emit-marker-expression {: #pip_emit-marker-expression }¶

exclude-newer {: #pip_exclude-newer }¶

extra {: #pip_extra }¶

extra-index-url {: #pip_extra-index-url }¶

find-links {: #pip_find-links }¶

`build-constraint-dependencies` {: #build-constraint-dependencies }¶

`conflicts` {: #conflicts }¶

`constraint-dependencies` {: #constraint-dependencies }¶

`default-groups` {: #default-groups }¶

`dev-dependencies` {: #dev-dependencies }¶

`environments` {: #environments }¶

`index` {: #index }¶

`managed` {: #managed }¶

`override-dependencies` {: #override-dependencies }¶

`package` {: #package }¶

`required-environments` {: #required-environments }¶

`sources` {: #sources }¶

`workspace`¶

`exclude` {: #workspace_exclude }¶

`members` {: #workspace_members }¶

`allow-insecure-host` {: #allow-insecure-host }¶

`cache-dir` {: #cache-dir }¶

`cache-keys` {: #cache-keys }¶

`check-url` {: #check-url }¶

`compile-bytecode` {: #compile-bytecode }¶

`concurrent-builds` {: #concurrent-builds }¶

`concurrent-downloads` {: #concurrent-downloads }¶

`concurrent-installs` {: #concurrent-installs }¶

`config-settings` {: #config-settings }¶

`dependency-metadata` {: #dependency-metadata }¶

`exclude-newer` {: #exclude-newer }¶

`extra-index-url` {: #extra-index-url }¶

`find-links` {: #find-links }¶

`fork-strategy` {: #fork-strategy }¶

`index` {: #index }¶

`index-strategy` {: #index-strategy }¶

`index-url` {: #index-url }¶

`keyring-provider` {: #keyring-provider }¶

`link-mode` {: #link-mode }¶

`native-tls` {: #native-tls }¶

`no-binary` {: #no-binary }¶

`no-binary-package` {: #no-binary-package }¶

`no-build` {: #no-build }¶

`no-build-isolation` {: #no-build-isolation }¶

`no-build-isolation-package` {: #no-build-isolation-package }¶

`no-build-package` {: #no-build-package }¶

`no-cache` {: #no-cache }¶

`no-index` {: #no-index }¶

`no-sources` {: #no-sources }¶

`offline` {: #offline }¶

`prerelease` {: #prerelease }¶

`preview` {: #preview }¶

`publish-url` {: #publish-url }¶

`pypy-install-mirror` {: #pypy-install-mirror }¶

`python-downloads` {: #python-downloads }¶

`python-install-mirror` {: #python-install-mirror }¶

`python-preference` {: #python-preference }¶

`reinstall` {: #reinstall }¶

`reinstall-package` {: #reinstall-package }¶

`required-version` {: #required-version }¶

`resolution` {: #resolution }¶

`trusted-publishing` {: #trusted-publishing }¶

`upgrade` {: #upgrade }¶

`upgrade-package` {: #upgrade-package }¶

`pip`¶

`all-extras` {: #pip_all-extras }¶

`allow-empty-requirements` {: #pip_allow-empty-requirements }¶

`annotation-style` {: #pip_annotation-style }¶

`break-system-packages` {: #pip_break-system-packages }¶

`compile-bytecode` {: #pip_compile-bytecode }¶

`config-settings` {: #pip_config-settings }¶

`custom-compile-command` {: #pip_custom-compile-command }¶

`dependency-metadata` {: #pip_dependency-metadata }¶

`emit-build-options` {: #pip_emit-build-options }¶

`emit-find-links` {: #pip_emit-find-links }¶

`emit-index-annotation` {: #pip_emit-index-annotation }¶

`emit-index-url` {: #pip_emit-index-url }¶

`emit-marker-expression` {: #pip_emit-marker-expression }¶

`exclude-newer` {: #pip_exclude-newer }¶

`extra` {: #pip_extra }¶

`extra-index-url` {: #pip_extra-index-url }¶

`find-links` {: #pip_find-links }¶

`fork-strategy` {: #pip_fork-strategy }¶

`generate-hashes` {: #pip_generate-hashes }¶

`index-strategy` {: #pip_index-strategy }¶