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:
[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"]
default-groups
The list of dependency-groups to install by default.
Default value: ["dev"]
Type: list[str]
Example usage:
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.
Use of this field is not recommend anymore. Instead, use the dependency-groups.dev field
which is a standardized way to declare development dependencies. The contents of
tool.uv.dev-dependencies and dependency-groups.dev are combined to determine the the
final requirements of the dev dependency group.
Default value: []
Type: list[str]
Example usage:
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:
[tool.uv]
# Resolve for macOS, but not for Linux or Windows.
environments = ["sys_platform == 'darwin'"]
index
The indexes to use when resolving dependencies.
Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.
Indexes are considered in the order in which they're defined, such that the first-defined
index has the highest priority. Further, the indexes provided by this setting are given
higher priority than any indexes specified via index_url or
extra_index_url. uv will only consider the first index that contains
a given package, unless an alternative index strategy is specified.
If an index is marked as explicit = true, it will be used exclusively for those
dependencies that select it explicitly via [tool.uv.sources], as in:
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
explicit = true
[tool.uv.sources]
torch = { index = "pytorch" }
If an index is marked as default = true, it will be moved to the end of the prioritized list, such that it is
given the lowest priority when resolving packages. Additionally, marking an index as default will disable the
PyPI default index.
Default value: []
Type: dict
Example usage:
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:
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.
Including a package as an override 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 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:
[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:
sources
The sources to use when resolving dependencies.
tool.uv.sources enriches the dependency metadata with additional sources, incorporated
during development. A dependency source can be a Git repository, a URL, a local path, or an
alternative registry.
See Dependencies for more.
Default value: {}
Type: dict
Example usage:
[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
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:
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:
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:
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:
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.:
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 commit, you can specify cache-keys = [{ git = { commit = true }, { file = "pyproject.toml" }]
to include the current Git commit hash in the cache key (in addition to the
pyproject.toml). Git tags are also supported via cache-keys = [{ git = { commit = true, tags = true } }].
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:
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:
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:
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:
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:
config-settings
Settings to pass to the PEP 517 build backend,
specified as KEY=VALUE pairs.
Default value: {}
Type: dict
Example usage:
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:
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:
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 or index with default = true. When multiple indexes
are provided, earlier values take priority.
To control uv's resolution strategy when multiple indexes are present, see
index_strategy.
(Deprecated: use index instead.)
Default value: []
Type: list[str]
Example usage:
find-links
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:
index
The package indexes to use when resolving dependencies.
Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.
Indexes are considered in the order in which they're defined, such that the first-defined
index has the highest priority. Further, the indexes provided by this setting are given
higher priority than any indexes specified via index_url or
extra_index_url. uv will only consider the first index that contains
a given package, unless an alternative index strategy is specified.
If an index is marked as explicit = true, it will be used exclusively for those
dependencies that select it explicitly via [tool.uv.sources], as in:
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
explicit = true
[tool.uv.sources]
torch = { index = "pytorch" }
If an index is marked as default = true, it will be moved to the end of the prioritized list, such that it is
given the lowest priority when resolving packages. Additionally, marking an index as default will disable the
PyPI default index.
Default value: "[]"
Type: dict
Example usage:
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 attacker can upload a malicious package under the
same name to an alternate index.
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:
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 or index.
(Deprecated: use index instead.)
Default value: "https://pypi.org/simple"
Type: str
Example usage:
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:
link-mode
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 thesite-packagesdirectory"copy": Copy packages from the wheel into thesite-packagesdirectory"hardlink": Hard link packages from the wheel into thesite-packagesdirectory"symlink": Symbolically link packages from the wheel into thesite-packagesdirectory
Example usage:
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:
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:
no-binary-package
Don't install pre-built wheels for a specific package.
Default value: []
Type: list[str]
Example usage:
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:
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:
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:
no-build-package
Don't build source distributions for a specific package.
Default value: []
Type: list[str]
Example usage:
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:
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:
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:
offline
Disable network access, relying only on locally cached data and locally available files.
Default value: false
Type: bool
Example usage:
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:
preview
Whether to enable experimental, preview features.
Default value: false
Type: bool
Example usage:
publish-url
The URL for publishing packages to the Python package index (by default: https://upload.pypi.org/legacy/).
Default value: "https://upload.pypi.org/legacy/"
Type: str
Example usage:
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:
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:
reinstall
Reinstall all packages, regardless of whether they're already installed. Implies refresh.
Default value: false
Type: bool
Example usage:
reinstall-package
Reinstall a specific package, regardless of whether it's already installed. Implies
refresh-package.
Default value: []
Type: list[str]
Example usage:
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:
trusted-publishing
Configure trusted publishing via GitHub Actions.
By default, uv checks for trusted publishing when running in GitHub Actions, but ignores it if it isn't configured or the workflow doesn't have enough permissions (e.g., a pull request from a fork).
Default value: automatic
Type: str
Example usage:
upgrade
Allow package upgrades, ignoring pinned versions in any existing output file.
Default value: false
Type: bool
Example usage:
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:
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:
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:
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:
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:
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:
config-settings
Settings to pass to the PEP 517 build backend,
specified as KEY=VALUE pairs.
Default value: {}
Type: dict
Example usage:
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:
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:
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:
emit-find-links
Include --find-links entries in the output file generated by uv pip compile.
Default value: false
Type: bool
Example usage:
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:
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:
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:
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:
extra
Include optional dependencies from the specified extra; may be provided more than once.
Only applies to pyproject.toml, setup.py, and setup.cfg sources.
Default value: []
Type: list[str]
Example usage:
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:
find-links
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:
generate-hashes
Include distribution hashes in the output file.
Default value: false
Type: bool
Example usage:
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 attacker can upload a malicious package under the
same name to an alternate index.
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:
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:
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:
link-mode
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 thesite-packagesdirectory"copy": Copy packages from the wheel into thesite-packagesdirectory"hardlink": Hard link packages from the wheel into thesite-packagesdirectory"symlink": Symbolically link packages from the wheel into thesite-packagesdirectory
Example usage:
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:
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:
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:
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:
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:
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:
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:
no-header
Exclude the comment header at the top of output file generated by uv pip compile.
Default value: false
Type: bool
Example usage:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
reinstall
Reinstall all packages, regardless of whether they're already installed. Implies refresh.
Default value: false
Type: bool
Example usage:
reinstall-package
Reinstall a specific package, regardless of whether it's already installed. Implies
refresh-package.
Default value: []
Type: list[str]
Example usage:
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:
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:
strict
Validate the Python environment, to detect packages with missing dependencies and other issues.
Default value: false
Type: bool
Example usage:
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:
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:
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:
upgrade
Allow package upgrades, ignoring pinned versions in any existing output file.
Default value: false
Type: bool
Example usage:
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:
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: