Skip to content

Settings

Project metadata#

constraint-dependencies#

Constraints to apply when resolving the project's dependencies.

Constraints are used to restrict the versions of dependencies that are selected during resolution.

Including a package as a constraint will not trigger installation of the package on its own; instead, the package must be requested elsewhere in the project's first-party or transitive dependencies.

Note

In uv lock, uv sync, and uv run, uv will only read constraint-dependencies from the pyproject.toml at the workspace root, and will ignore any declarations in other workspace members or uv.toml files.

Default value: []

Type: list[str]

Example usage:

pyproject.toml
[tool.uv]
# Ensure that the grpcio version is always less than 1.65, if it's requested by a
# transitive dependency.
constraint-dependencies = ["grpcio<1.65"]

dev-dependencies#

The project's development dependencies. Development dependencies will be installed by default in uv run and uv sync, but will not appear in the project's published metadata.

Default value: []

Type: list[str]

Example usage:

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

environments#

A list of supported environments against which to resolve dependencies.

By default, uv will resolve for all possible environments during a uv lock operation. However, you can restrict the set of supported environments to improve performance and avoid unsatisfiable branches in the solution space.

These environments will also respected when uv pip compile is invoked with the --universal flag.

Default value: []

Type: str | list[str]

Example usage:

pyproject.toml
[tool.uv]
# Resolve for macOS, but not for Linux or Windows.
environments = ["sys_platform == 'darwin'"]

managed#

Whether the project is managed by uv. If false, uv will ignore the project when uv run is invoked.

Default value: true

Type: bool

Example usage:

pyproject.toml
[tool.uv]
managed = false

override-dependencies#

Overrides to apply when resolving the project's dependencies.

Overrides are used to force selection of a specific version of a package, regardless of the version requested by any other package, and regardless of whether choosing that version would typically constitute an invalid resolution.

While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of any constituent packages.

Note

In uv lock, uv sync, and uv run, uv will only read override-dependencies from the pyproject.toml at the workspace root, and will ignore any declarations in other workspace members or uv.toml files.

Default value: []

Type: list[str]

Example usage:

pyproject.toml
[tool.uv]
# Always install Werkzeug 2.3.0, regardless of whether transitive dependencies request
# a different version.
override-dependencies = ["werkzeug==2.3.0"]

package#

Whether the project should be considered a Python package, or a non-package ("virtual") project.

Packages are built and installed into the virtual environment in editable mode and thus require a build backend, while virtual projects are not built or installed; instead, only their dependencies are included in the virtual environment.

Creating a package requires that a build-system is present in the pyproject.toml, and that the project adheres to a structure that adheres to the build backend's expectations (e.g., a src layout).

Default value: true

Type: bool

Example usage:

pyproject.toml
[tool.uv]
package = false

workspace#

exclude#

Packages to exclude as workspace members. If a package matches both members and exclude, it will be excluded.

Supports both globs and explicit paths.

For more information on the glob syntax, refer to the glob documentation.

Default value: []

Type: list[str]

Example usage:

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

members#

Packages to include as workspace members.

Supports both globs and explicit paths.

For more information on the glob syntax, refer to the glob documentation.

Default value: []

Type: list[str]

Example usage:

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

Configuration#

allow-insecure-host#

Allow insecure connections to host.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

Default value: []

Type: list[str]

Example usage:

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

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

cache-dir#

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and %LOCALAPPDATA%\uv\cache on Windows.

Default value: None

Type: str

Example usage:

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

cache-dir = "./.uv_cache"

cache-keys#

The keys to consider when caching builds for the project.

Cache keys enable you to specify the files or directories that should trigger a rebuild when modified. By default, uv will rebuild a project whenever the pyproject.toml, setup.py, or setup.cfg files in the project directory are modified, i.e.:

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

As an example: if a project uses dynamic metadata to read its dependencies from a requirements.txt file, you can specify cache-keys = [{ file = "requirements.txt" }, { file = "pyproject.toml" }] to ensure that the project is rebuilt whenever the requirements.txt file is modified (in addition to watching the pyproject.toml).

Globs are supported, following the syntax of the glob crate. For example, to invalidate the cache whenever a .toml file in the project directory or any of its subdirectories is modified, you can specify cache-keys = [{ file = "**/*.toml" }]. Note that the use of globs can be expensive, as uv may need to walk the filesystem to determine whether any files have changed.

Cache keys can also include version control information. For example, if a project uses setuptools_scm to read its version from a Git tag, you can specify cache-keys = [{ git = true }, { file = "pyproject.toml" }] to include the current Git commit hash in the cache key (in addition to the pyproject.toml).

Cache keys only affect the project defined by the pyproject.toml in which they're specified (as opposed to, e.g., affecting all members in a workspace), and all paths and globs are interpreted as relative to the project directory.

Default value: [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }]

Type: list[dict]

Example usage:

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

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

compile-bytecode#

Compile Python files to bytecode after installation.

By default, uv does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, uv will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

Default value: false

Type: bool

Example usage:

[tool.uv]
compile-bytecode = true

compile-bytecode = true

concurrent-builds#

The maximum number of source distributions that uv will build concurrently at any given time.

Defaults to the number of available CPU cores.

Default value: None

Type: int

Example usage:

[tool.uv]
concurrent-builds = 4

concurrent-builds = 4

concurrent-downloads#

The maximum number of in-flight concurrent downloads that uv will perform at any given time.

Default value: 50

Type: int

Example usage:

[tool.uv]
concurrent-downloads = 4

concurrent-downloads = 4

concurrent-installs#

The number of threads used when installing and unzipping packages.

Defaults to the number of available CPU cores.

Default value: None

Type: int

Example usage:

[tool.uv]
concurrent-installs = 4

concurrent-installs = 4

config-settings#

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs.

Default value: {}

Type: dict

Example usage:

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

config-settings = { editable_mode = "compat" }

dependency-metadata#

Pre-defined static metadata for dependencies of the project (direct or transitive). When provided, enables the resolver to use the specified metadata instead of querying the registry or building the relevant package from source.

Metadata should be provided in adherence with the Metadata 2.3 standard, though only the following fields are respected:

  • name: The name of the package.
  • (Optional) version: The version of the package. If omitted, the metadata will be applied to all versions of the package.
  • (Optional) requires-dist: The dependencies of the package (e.g., werkzeug>=0.14).
  • (Optional) requires-python: The Python version required by the package (e.g., >=3.10).
  • (Optional) provides-extras: The extras provided by the package.

Default value: []

Type: list[dict]

Example usage:

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

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

exclude-newer#

Limit candidate packages to those that were uploaded prior to the given date.

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

Default value: None

Type: str

Example usage:

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

exclude-newer = "2006-12-02"

extra-index-url#

Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by index_url. When multiple indexes are provided, earlier values take priority.

To control uv's resolution strategy when multiple indexes are present, see index_strategy.

Default value: []

Type: list[str]

Example usage:

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

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

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

Default value: []

Type: list[str]

Example usage:

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

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

index-strategy#

The strategy to use when resolving against multiple index URLs.

By default, uv will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

Default value: "first-index"

Possible values:

  • "first-index": Only use results from the first index that returns a match for a given package name
  • "unsafe-first-match": Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
  • "unsafe-best-match": Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

Example usage:

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

index-strategy = "unsafe-best-match"

index-url#

The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index provided by this setting is given lower priority than any indexes specified via extra_index_url.

Default value: "https://pypi.org/simple"

Type: str

Example usage:

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

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

keyring-provider#

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures uv to use the keyring CLI to handle authentication.

Default value: "disabled"

Type: str

Example usage:

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

keyring-provider = "subprocess"

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and Windows.

Default value: "clone" (macOS) or "hardlink" (Linux, Windows)

Possible values:

  • "clone": Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
  • "copy": Copy packages from the wheel into the site-packages directory
  • "hardlink": Hard link packages from the wheel into the site-packages directory
  • "symlink": Symbolically link packages from the wheel into the site-packages directory

Example usage:

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

link-mode = "copy"

native-tls#

Whether to load TLS certificates from the platform's native certificate store.

By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.

Default value: false

Type: bool

Example usage:

[tool.uv]
native-tls = true

native-tls = true

no-binary#

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

Default value: false

Type: bool

Example usage:

[tool.uv]
no-binary = true

no-binary = true

no-binary-package#

Don't install pre-built wheels for a specific package.

Default value: []

Type: list[str]

Example usage:

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

no-binary-package = ["ruff"]

no-build#

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Default value: false

Type: bool

Example usage:

[tool.uv]
no-build = true

no-build = true

no-build-isolation#

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

Default value: false

Type: bool

Example usage:

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

no-build-isolation = true

no-build-isolation-package#

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

Default value: []

Type: Vec<PackageName>

Example usage:

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

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

no-build-package#

Don't build source distributions for a specific package.

Default value: []

Type: list[str]

Example usage:

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

no-build-package = ["ruff"]

no-cache#

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation.

Default value: false

Type: bool

Example usage:

[tool.uv]
no-cache = true

no-cache = true

no-index#

Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links.

Default value: false

Type: bool

Example usage:

[tool.uv]
no-index = true

no-index = true

no-sources#

Ignore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any local or Git sources.

Default value: false

Type: bool

Example usage:

[tool.uv]
no-sources = true

no-sources = true

offline#

Disable network access, relying only on locally cached data and locally available files.

Default value: false

Type: bool

Example usage:

[tool.uv]
offline = true

offline = true

prerelease#

The strategy to use when considering pre-release versions.

By default, uv will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

Default value: "if-necessary-or-explicit"

Possible values:

  • "disallow": Disallow all pre-release versions
  • "allow": Allow all pre-release versions
  • "if-necessary": Allow pre-release versions if all versions of a package are pre-release
  • "explicit": Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
  • "if-necessary-or-explicit": Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

Example usage:

[tool.uv]
prerelease = "allow"

prerelease = "allow"

preview#

Whether to enable experimental, preview features.

Default value: false

Type: bool

Example usage:

[tool.uv]
preview = true

preview = true

python-downloads#

Whether to allow Python downloads.

Default value: "automatic"

Possible values:

  • "automatic": Automatically download managed Python installations when needed
  • "manual": Do not automatically download managed Python installations; require explicit installation
  • "never": Do not ever allow Python downloads

Example usage:

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

python-downloads = "manual"

python-preference#

Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv.

Default value: "managed"

Possible values:

  • "only-managed": Only use managed Python installations; never use system Python installations
  • "managed": Prefer managed Python installations over system Python installations
  • "system": Prefer system Python installations over managed Python installations
  • "only-system": Only use system Python installations; never use managed Python installations

Example usage:

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

python-preference = "managed"

reinstall#

Reinstall all packages, regardless of whether they're already installed. Implies refresh.

Default value: false

Type: bool

Example usage:

[tool.uv]
reinstall = true

reinstall = true

reinstall-package#

Reinstall a specific package, regardless of whether it's already installed. Implies refresh-package.

Default value: []

Type: list[str]

Example usage:

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

reinstall-package = ["ruff"]

resolution#

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, uv will use the latest compatible version of each package (highest).

Default value: "highest"

Possible values:

  • "highest": Resolve the highest compatible version of each package
  • "lowest": Resolve the lowest compatible version of each package
  • "lowest-direct": Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

Example usage:

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

resolution = "lowest-direct"

upgrade#

Allow package upgrades, ignoring pinned versions in any existing output file.

Default value: false

Type: bool

Example usage:

[tool.uv]
upgrade = true

upgrade = true

upgrade-package#

Allow upgrades for a specific package, ignoring pinned versions in any existing output file.

Accepts both standalone package names (ruff) and version specifiers (ruff<0.5.0).

Default value: []

Type: list[str]

Example usage:

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

upgrade-package = ["ruff"]

pip#

Settings that are specific to the uv pip command-line interface.

These values will be ignored when running commands outside the uv pip namespace (e.g., uv lock, uvx).

all-extras#

Include all optional dependencies.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

Default value: false

Type: bool

Example usage:

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

[pip]
all-extras = true

allow-empty-requirements#

Allow uv pip sync with empty requirements, which will clear the environment of all packages.

Default value: false

Type: bool

Example usage:

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

[pip]
allow-empty-requirements = true

allow-insecure-host#

Allow insecure connections to host.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

Default value: []

Type: list[str]

Example usage:

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

[pip]
allow-insecure-host = ["localhost:8080"]

annotation-style#

The style of the annotation comments included in the output file, used to indicate the source of each package.

Default value: "split"

Possible values:

  • "line": Render the annotations on a single, comma-separated line
  • "split": Render each annotation on its own line

Example usage:

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

[pip]
annotation-style = "line"

break-system-packages#

Allow uv to modify an EXTERNALLY-MANAGED Python installation.

WARNING: --break-system-packages is intended for use in continuous integration (CI) environments, when installing into Python installations that are managed by an external package manager, like apt. It should be used with caution, as such Python installations explicitly recommend against modifications by other package managers (like uv or pip).

Default value: false

Type: bool

Example usage:

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

[pip]
break-system-packages = true

compile-bytecode#

Compile Python files to bytecode after installation.

By default, uv does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, uv will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

Default value: false

Type: bool

Example usage:

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

[pip]
compile-bytecode = true

config-settings#

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs.

Default value: {}

Type: dict

Example usage:

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

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

custom-compile-command#

The header comment to include at the top of the output file generated by uv pip compile.

Used to reflect custom build scripts and commands that wrap uv pip compile.

Default value: None

Type: str

Example usage:

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

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

dependency-metadata#

Pre-defined static metadata for dependencies of the project (direct or transitive). When provided, enables the resolver to use the specified metadata instead of querying the registry or building the relevant package from source.

Metadata should be provided in adherence with the Metadata 2.3 standard, though only the following fields are respected:

  • name: The name of the package.
  • (Optional) version: The version of the package. If omitted, the metadata will be applied to all versions of the package.
  • (Optional) requires-dist: The dependencies of the package (e.g., werkzeug>=0.14).
  • (Optional) requires-python: The Python version required by the package (e.g., >=3.10).
  • (Optional) provides-extras: The extras provided by the package.

Default value: []

Type: list[dict]

Example usage:

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

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

emit-build-options#

Include --no-binary and --only-binary entries in the output file generated by uv pip compile.

Default value: false

Type: bool

Example usage:

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

[pip]
emit-build-options = true

Include --find-links entries in the output file generated by uv pip compile.

Default value: false

Type: bool

Example usage:

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

[pip]
emit-find-links = true

emit-index-annotation#

Include comment annotations indicating the index used to resolve each package (e.g., # from https://pypi.org/simple).

Default value: false

Type: bool

Example usage:

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

[pip]
emit-index-annotation = true

emit-index-url#

Include --index-url and --extra-index-url entries in the output file generated by uv pip compile.

Default value: false

Type: bool

Example usage:

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

[pip]
emit-index-url = true

emit-marker-expression#

Whether to emit a marker string indicating the conditions under which the set of pinned dependencies is valid.

The pinned dependencies may be valid even when the marker expression is false, but when the expression is true, the requirements are known to be correct.

Default value: false

Type: bool

Example usage:

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

[pip]
emit-marker-expression = true

exclude-newer#

Limit candidate packages to those that were uploaded prior to the given date.

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

Default value: None

Type: str

Example usage:

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

[pip]
exclude-newer = "2006-12-02"

extra#

Include optional dependencies from the extra group name; may be provided more than once.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

Default value: []

Type: list[str]

Example usage:

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

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

extra-index-url#

Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by index_url. When multiple indexes are provided, earlier values take priority.

To control uv's resolution strategy when multiple indexes are present, see index_strategy.

Default value: []

Type: list[str]

Example usage:

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

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

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

Default value: []

Type: list[str]

Example usage:

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

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

generate-hashes#

Include distribution hashes in the output file.

Default value: false

Type: bool

Example usage:

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

[pip]
generate-hashes = true

index-strategy#

The strategy to use when resolving against multiple index URLs.

By default, uv will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

Default value: "first-index"

Possible values:

  • "first-index": Only use results from the first index that returns a match for a given package name
  • "unsafe-first-match": Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
  • "unsafe-best-match": Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

Example usage:

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

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

index-url#

The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index provided by this setting is given lower priority than any indexes specified via extra_index_url.

Default value: "https://pypi.org/simple"

Type: str

Example usage:

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

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

keyring-provider#

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures uv to use the keyring CLI to handle authentication.

Default value: disabled

Type: str

Example usage:

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

[pip]
keyring-provider = "subprocess"

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and Windows.

Default value: "clone" (macOS) or "hardlink" (Linux, Windows)

Possible values:

  • "clone": Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
  • "copy": Copy packages from the wheel into the site-packages directory
  • "hardlink": Hard link packages from the wheel into the site-packages directory
  • "symlink": Symbolically link packages from the wheel into the site-packages directory

Example usage:

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

[pip]
link-mode = "copy"

no-annotate#

Exclude comment annotations indicating the source of each package from the output file generated by uv pip compile.

Default value: false

Type: bool

Example usage:

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

[pip]
no-annotate = true

no-binary#

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

Default value: []

Type: list[str]

Example usage:

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

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

no-build#

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Alias for --only-binary :all:.

Default value: false

Type: bool

Example usage:

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

[pip]
no-build = true

no-build-isolation#

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

Default value: false

Type: bool

Example usage:

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

[pip]
no-build-isolation = true

no-build-isolation-package#

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

Default value: []

Type: Vec<PackageName>

Example usage:

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

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

no-deps#

Ignore package dependencies, instead only add those packages explicitly listed on the command line to the resulting the requirements file.

Default value: false

Type: bool

Example usage:

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

[pip]
no-deps = true

no-emit-package#

Specify a package to omit from the output resolution. Its dependencies will still be included in the resolution. Equivalent to pip-compile's --unsafe-package option.

Default value: []

Type: list[str]

Example usage:

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

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

no-header#

Exclude the comment header at the top of output file generated by uv pip compile.

Default value: false

Type: bool

Example usage:

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

[pip]
no-header = true

no-index#

Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links.

Default value: false

Type: bool

Example usage:

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

[pip]
no-index = true

no-sources#

Ignore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any local or Git sources.

Default value: false

Type: bool

Example usage:

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

[pip]
no-sources = true

no-strip-extras#

Include extras in the output file.

By default, uv strips extras, as any packages pulled in by the extras are already included as dependencies in the output file directly. Further, output files generated with --no-strip-extras cannot be used as constraints files in install and sync invocations.

Default value: false

Type: bool

Example usage:

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

[pip]
no-strip-extras = true

no-strip-markers#

Include environment markers in the output file generated by uv pip compile.

By default, uv strips environment markers, as the resolution generated by compile is only guaranteed to be correct for the target environment.

Default value: false

Type: bool

Example usage:

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

[pip]
no-strip-markers = true

only-binary#

Only use pre-built wheels; don't build source distributions.

When enabled, resolving will not run code from the given packages. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

Default value: []

Type: list[str]

Example usage:

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

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

output-file#

Write the requirements generated by uv pip compile to the given requirements.txt file.

If the file already exists, the existing versions will be preferred when resolving dependencies, unless --upgrade is also specified.

Default value: None

Type: str

Example usage:

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

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

prefix#

Install packages into lib, bin, and other top-level folders under the specified directory, as if a virtual environment were present at that location.

In general, prefer the use of --python to install into an alternate environment, as scripts and other artifacts installed via --prefix will reference the installing interpreter, rather than any interpreter added to the --prefix directory, rendering them non-portable.

Default value: None

Type: str

Example usage:

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

[pip]
prefix = "./prefix"

prerelease#

The strategy to use when considering pre-release versions.

By default, uv will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

Default value: "if-necessary-or-explicit"

Possible values:

  • "disallow": Disallow all pre-release versions
  • "allow": Allow all pre-release versions
  • "if-necessary": Allow pre-release versions if all versions of a package are pre-release
  • "explicit": Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
  • "if-necessary-or-explicit": Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

Example usage:

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

[pip]
prerelease = "allow"

python#

The Python interpreter into which packages should be installed.

By default, uv installs into the virtual environment in the current working directory or any parent directory. The --python option allows you to specify a different interpreter, which is intended for use in continuous integration (CI) environments or other automated workflows.

Supported formats: - 3.10 looks for an installed Python 3.10 in the registry on Windows (see py --list-paths), or python3.10 on Linux and macOS. - python3.10 or python.exe looks for a binary with the given name in PATH. - /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.

Default value: None

Type: str

Example usage:

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

[pip]
python = "3.10"

python-platform#

The platform for which requirements should be resolved.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

Default value: None

Type: str

Example usage:

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

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

python-version#

The minimum Python version that should be supported by the resolved requirements (e.g., 3.8 or 3.8.17).

If a patch version is omitted, the minimum patch version is assumed. For example, 3.8 is mapped to 3.8.0.

Default value: None

Type: str

Example usage:

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

[pip]
python-version = "3.8"

reinstall#

Reinstall all packages, regardless of whether they're already installed. Implies refresh.

Default value: false

Type: bool

Example usage:

[tool.uv.pip]
reinstall = true

[pip]
reinstall = true

reinstall-package#

Reinstall a specific package, regardless of whether it's already installed. Implies refresh-package.

Default value: []

Type: list[str]

Example usage:

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

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

require-hashes#

Require a matching hash for each requirement.

Hash-checking mode is all or nothing. If enabled, all requirements must be provided with a corresponding hash or set of hashes. Additionally, if enabled, all requirements must either be pinned to exact versions (e.g., ==1.0.0), or be specified via direct URL.

Hash-checking mode introduces a number of additional constraints:

  • Git dependencies are not supported.
  • Editable installs are not supported.
  • Local dependencies are not supported, unless they point to a specific wheel (.whl) or source archive (.zip, .tar.gz), as opposed to a directory.

Default value: false

Type: bool

Example usage:

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

[pip]
require-hashes = true

resolution#

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, uv will use the latest compatible version of each package (highest).

Default value: "highest"

Possible values:

  • "highest": Resolve the highest compatible version of each package
  • "lowest": Resolve the lowest compatible version of each package
  • "lowest-direct": Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

Example usage:

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

[pip]
resolution = "lowest-direct"

strict#

Validate the Python environment, to detect packages with missing dependencies and other issues.

Default value: false

Type: bool

Example usage:

[tool.uv.pip]
strict = true

[pip]
strict = true

system#

Install packages into the system Python environment.

By default, uv installs into the virtual environment in the current working directory or any parent directory. The --system option instructs uv to instead use the first Python found in the system PATH.

WARNING: --system is intended for use in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

Default value: false

Type: bool

Example usage:

[tool.uv.pip]
system = true

[pip]
system = true

target#

Install packages into the specified directory, rather than into the virtual or system Python environment. The packages will be installed at the top-level of the directory.

Default value: None

Type: str

Example usage:

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

[pip]
target = "./target"

universal#

Perform a universal resolution, attempting to generate a single requirements.txt output file that is compatible with all operating systems, architectures, and Python implementations.

In universal mode, the current Python version (or user-provided --python-version) will be treated as a lower bound. For example, --universal --python-version 3.7 would produce a universal resolution for Python 3.7 and later.

Default value: false

Type: bool

Example usage:

[tool.uv.pip]
universal = true

[pip]
universal = true

upgrade#

Allow package upgrades, ignoring pinned versions in any existing output file.

Default value: false

Type: bool

Example usage:

[tool.uv.pip]
upgrade = true

[pip]
upgrade = true

upgrade-package#

Allow upgrades for a specific package, ignoring pinned versions in any existing output file.

Accepts both standalone package names (ruff) and version specifiers (ruff<0.5.0).

Default value: []

Type: list[str]

Example usage:

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

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

verify-hashes#

Validate any hashes provided in the requirements file.

Unlike --require-hashes, --verify-hashes does not require that all requirements have hashes; instead, it will limit itself to verifying the hashes of those requirements that do include them.

Default value: false

Type: bool

Example usage:

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

[pip]
verify-hashes = true