CLI Reference
uv
An extremely fast Python package manager.
Usage
Commands
uv run
Run a command or script
uv init
Create a new project
uv add
Add dependencies to the project
uv remove
Remove dependencies from the project
uv sync
Update the project’s environment
uv lock
Update the project’s lockfile
uv export
Export the project’s lockfile to an alternate format
uv tree
Display the project’s dependency tree
uv tool
Run and install commands provided by Python packages
uv python
Manage Python versions and installations
uv pip
Manage Python packages with a pip-compatible interface
uv venv
Create a virtual environment
uv build
Build Python packages into source distributions and wheels
uv publish
Upload distributions to an index
uv cache
Manage uv’s cache
uv self
Manage the uv executable
uv version
Display uv’s version
uv help
Display documentation for a command
uv run
Run a command or script.
Ensures that the command runs in a Python environment.
When used with a file ending in .py
or an HTTP(S) URL, the file will be treated as a script and run with a Python interpreter, i.e., uv run file.py
is equivalent to uv run python file.py
. For URLs, the script is temporarily downloaded before execution. If the script contains inline dependency metadata, it will be installed into an isolated, ephemeral environment. When used with -
, the input will be read from stdin, and treated as a Python script.
When used in a project, the project environment will be created and updated before invoking the command.
When used outside a project, if a virtual environment can be found in the current directory or a parent directory, the command will be run in that environment. Otherwise, the command will be run in the environment of the discovered interpreter.
Arguments following the command (or script) are not interpreted as arguments to uv. All options to uv must be provided before the command, e.g., uv run --verbose foo
. A --
can be used to separate the command from uv options for clarity, e.g., uv run --python 3.12 -- python
.
Usage
Options
--all-extras
Include all optional dependencies.
Optional dependencies are defined via
project.optional-dependencies
in apyproject.toml
.This option is only available when running in a project.
--all-groups
Include dependencies from all dependency groups.
--no-group
can be used to exclude specific groups.--all-packages
Run the command with all workspace members installed.
The workspace’s environment (
.venv
) is updated to include all workspace members.Any extras or groups specified via
--extra
,--group
, or related options will be applied to all workspace members.--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--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.
May also be set with the
UV_COMPILE_BYTECODE
environment variable.--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--env-file
env-fileLoad environment variables from a
.env
file.Can be provided multiple times, with subsequent files overriding values defined in previous files.
May also be set with the
UV_ENV_FILE
environment variable.--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra
extraInclude optional dependencies from the specified extra name.
May be provided more than once.
Optional dependencies are defined via
project.optional-dependencies
in apyproject.toml
.This option is only available when running in a project.
--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--frozen
Run without updating the
uv.lock
file.Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the
pyproject.toml
includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.May also be set with the
UV_FROZEN
environment variable.--group
groupInclude dependencies from the specified dependency group.
May be provided multiple times.
--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--isolated
Run the command in an isolated virtual environment.
Usually, the project environment is reused for performance. This option forces a fresh environment to be used for the project, enforcing strict isolation between dependencies and declaration of requirements.
An editable installation is still used for the project.
When used with
--with
or--with-requirements
, the additional dependencies will still be layered in a second environment.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--locked
Assert that the
uv.lock
will remain unchanged.Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the
UV_LOCKED
environment variable.--module
,-m
Run a Python module.
Equivalent to
python -m <module>
.--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--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.
--no-binary-package
no-binary-packageDon’t install pre-built wheels for a specific package
--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.
--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-build-package
no-build-packageDon’t build source distributions for a specific package
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-dev
Omit the development dependency group.
This option is an alias of
--no-group dev
.This option is only available when running in a project.
--no-editable
Install any editable dependencies, including the project and any workspace members, as non-editable
--no-env-file
Avoid reading environment variables from a
.env
fileMay also be set with the
UV_NO_ENV_FILE
environment variable.--no-extra
no-extraExclude the specified optional dependencies, if
--all-extras
is supplied.May be provided multiple times.
--no-group
no-groupExclude dependencies from the specified dependency group.
May be provided multiple times.
--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-project
Avoid discovering the project or workspace.
Instead of searching for projects in the current directory and parent directories, run in an isolated, ephemeral environment populated by the
--with
requirements.If a virtual environment is active or found in a current or parent directory, it will be used as if there was no project or workspace.
--no-python-downloads
Disable automatic downloads of Python.
--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--no-sync
Avoid syncing the virtual environment.
Implies
--frozen
, as the project dependencies will be ignored (i.e., the lockfile will not be updated, since the environment will not be synced regardless).May also be set with the
UV_NO_SYNC
environment variable.--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--only-dev
Only include the development dependency group.
Omit other dependencies. The project itself will also be omitted.
This option is an alias for
--only-group dev
.--only-group
only-groupOnly include dependencies from the specified dependency group.
May be provided multiple times.
The project itself will also be omitted.
--package
packageRun the command in a specific package in the workspace.
If the workspace member does not exist, uv will exit with an error.
--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter to use for the run environment.
If the interpreter request is satisfied by a discovered environment, the environment will be used.
See uv python to view supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--refresh
Refresh all cached data
--refresh-package
refresh-packageRefresh cached data for a specific package
--reinstall
Reinstall all packages, regardless of whether they’re already installed. Implies
--refresh
--reinstall-package
reinstall-packageReinstall a specific package, regardless of whether it’s already installed. Implies
--refresh-package
--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script
,-s
Run the given path as a Python script.
Using
--script
will attempt to parse the path as a PEP 723 script, irrespective of its extension.--upgrade
,-U
Allow package upgrades, ignoring pinned versions in any existing output file. Implies
--refresh
--upgrade-package
,-P
upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies
--refresh-package
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
--with
withRun with the given packages installed.
When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.
--with-editable
with-editableRun with the given packages installed as editables.
When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.
--with-requirements
with-requirementsRun with all packages listed in the given
requirements.txt
files.The same environment semantics as
--with
apply.Using
pyproject.toml
,setup.py
, orsetup.cfg
files is not allowed.
uv init
Create a new project.
Follows the pyproject.toml
specification.
If a pyproject.toml
already exists at the target, uv will exit with an error.
If a pyproject.toml
is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent.
Some project state is not created until needed, e.g., the project virtual environment (.venv
) and lockfile (uv.lock
) are lazily created during the first sync.
Usage
Arguments
PATH
The path to use for the project/script.
Defaults to the current working directory when initializing an app or library; required when initializing a script. Accepts relative and absolute paths.
If a
pyproject.toml
is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent, unless--no-workspace
is provided.
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--app
Create a project for an application.
This is the default behavior if
--lib
is not requested.This project kind is for web servers, scripts, and command-line interfaces.
By default, an application is not intended to be built and distributed as a Python package. The
--package
option can be used to create an application that is distributable, e.g., if you want to distribute a command-line interface via PyPI.--author-from
author-fromFill in the
authors
field in thepyproject.toml
.By default, uv will attempt to infer the author information from some sources (e.g., Git) (
auto
). Use--author-from git
to only infer from Git configuration. Use--author-from none
to avoid inferring the author information.Possible values:
auto
: Fetch the author information from some sources (e.g., Git) automaticallygit
: Fetch the author information from Git configuration onlynone
: Do not infer the author information
--build-backend
build-backendInitialize a build-backend of choice for the project.
Implicitly sets
--package
.Possible values:
hatch
: Use hatchling as the project build backendflit
: Use flit-core as the project build backendpdm
: Use pdm-backend as the project build backendsetuptools
: Use setuptools as the project build backendmaturin
: Use maturin as the project build backendscikit
: Use scikit-build-core as the project build backend
--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--lib
Create a project for a library.
A library is a project that is intended to be built and distributed as a Python package.
--name
nameThe name of the project.
Defaults to the name of the directory.
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-package
Do not set up the project to be built as a Python package.
Does not include a
[build-system]
for the project.This is the default behavior when using
--app
.--no-pin-python
Do not create a
.python-version
file for the project.By default, uv will create a
.python-version
file containing the minor version of the discovered Python interpreter, which will cause subsequent uv commands to use that version.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--no-readme
Do not create a
README.md
file--no-workspace
Avoid discovering a workspace and create a standalone project.
By default, uv searches for workspaces in the current directory or any parent directory.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--package
Set up the project to be built as a Python package.
Defines a
[build-system]
for the project.This is the default behavior when using
--lib
or--build-backend
.When using
--app
, this will include a[project.scripts]
entrypoint and use asrc/
project structure.--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter to use to determine the minimum supported Python version.
See uv python to view supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--script
Create a script.
A script is a standalone file with embedded metadata enumerating its dependencies, along with any Python version requirements, as defined in the PEP 723 specification.
PEP 723 scripts can be executed directly with
uv run
.By default, adds a requirement on the system Python version; use
--python
to specify an alternative Python version requirement.--vcs
vcsInitialize a version control system for the project.
By default, uv will initialize a Git repository (
git
). Use--vcs none
to explicitly avoid initializing a version control system.Possible values:
git
: Use Git for version controlnone
: Do not use any version control system
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv add
Add dependencies to the project.
Dependencies are added to the project's pyproject.toml
file.
If a given dependency exists already, it will be updated to the new version specifier unless it includes markers that differ from the existing specifier in which case another entry for the dependency will be added.
If no constraint or URL is provided for a dependency, a lower bound is added equal to the latest compatible version of the package, e.g., >=1.2.3
, unless --frozen
is provided, in which case no resolution is performed.
The lockfile and project environment will be updated to reflect the added dependencies. To skip updating the lockfile, use --frozen
. To skip updating the environment, use --no-sync
.
If any of the requested dependencies cannot be found, uv will exit with an error, unless the --frozen
flag is provided, in which case uv will add the dependencies verbatim without checking that they exist or are compatible with the project.
uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.
Usage
Arguments
PACKAGES
The packages to add, as PEP 508 requirements (e.g.,
ruff==0.5.0
)
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--branch
branchBranch to use when adding a dependency from Git
--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--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.
May also be set with the
UV_COMPILE_BYTECODE
environment variable.--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--dev
Add the requirements to the development dependency group.
This option is an alias for
--group dev
.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--editable
Add the requirements as editable
--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra
extraExtras to enable for the dependency.
May be provided more than once.
To add this dependency to an optional extra instead, see
--optional
.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--frozen
Add dependencies without re-locking the project.
The project environment will not be synced.
May also be set with the
UV_FROZEN
environment variable.--group
groupAdd the requirements to the specified dependency group.
These requirements will not be included in the published metadata for the project.
--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--locked
Assert that the
uv.lock
will remain unchanged.Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the
UV_LOCKED
environment variable.--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--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.
--no-binary-package
no-binary-packageDon’t install pre-built wheels for a specific package
--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.
--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-build-package
no-build-packageDon’t build source distributions for a specific package
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--no-sync
Avoid syncing the virtual environment
May also be set with the
UV_NO_SYNC
environment variable.--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--optional
optionalAdd the requirements to the package’s optional dependencies for the specified extra.
The group may then be activated when installing the project with the
--extra
flag.To enable an optional extra for this requirement instead, see
--extra
.--package
packageAdd the dependency to a specific package in the workspace
--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter to use for resolving and syncing.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--raw-sources
Add source requirements to
project.dependencies
, rather thantool.uv.sources
.By default, uv will use the
tool.uv.sources
section to record source information for Git, local, editable, and direct URL requirements.--refresh
Refresh all cached data
--refresh-package
refresh-packageRefresh cached data for a specific package
--reinstall
Reinstall all packages, regardless of whether they’re already installed. Implies
--refresh
--reinstall-package
reinstall-packageReinstall a specific package, regardless of whether it’s already installed. Implies
--refresh-package
--requirements
,-r
requirementsAdd all packages listed in the given
requirements.txt
files--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--rev
revCommit to use when adding a dependency from Git
--script
scriptAdd the dependency to the specified Python script, rather than to a project.
If provided, uv will add the dependency to the script’s inline metadata table, in adherence with PEP 723. If no such inline metadata table is present, a new one will be created and added to the script. When executed via
uv run
, uv will create a temporary environment for the script with all inline dependencies installed.--tag
tagTag to use when adding a dependency from Git
--upgrade
,-U
Allow package upgrades, ignoring pinned versions in any existing output file. Implies
--refresh
--upgrade-package
,-P
upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies
--refresh-package
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv remove
Remove dependencies from the project.
Dependencies are removed from the project's pyproject.toml
file.
If multiple entries exist for a given dependency, i.e., each with different markers, all of the entries will be removed.
The lockfile and project environment will be updated to reflect the removed dependencies. To skip updating the lockfile, use --frozen
. To skip updating the environment, use --no-sync
.
If any of the requested dependencies are not present in the project, uv will exit with an error.
If a package has been manually installed in the environment, i.e., with uv pip install
, it will not be removed by uv remove
.
uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.
Usage
Arguments
PACKAGES
The names of the dependencies to remove (e.g.,
ruff
)
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--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.
May also be set with the
UV_COMPILE_BYTECODE
environment variable.--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--dev
Remove the packages from the development dependency group.
This option is an alias for
--group dev
.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--frozen
Remove dependencies without re-locking the project.
The project environment will not be synced.
May also be set with the
UV_FROZEN
environment variable.--group
groupRemove the packages from the specified dependency group
--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--locked
Assert that the
uv.lock
will remain unchanged.Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the
UV_LOCKED
environment variable.--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--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.
--no-binary-package
no-binary-packageDon’t install pre-built wheels for a specific package
--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.
--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-build-package
no-build-packageDon’t build source distributions for a specific package
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--no-sync
Avoid syncing the virtual environment after re-locking the project
May also be set with the
UV_NO_SYNC
environment variable.--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--optional
optionalRemove the packages from the project’s optional dependencies for the specified extra
--package
packageRemove the dependencies from a specific package in the workspace
--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter to use for resolving and syncing.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--refresh
Refresh all cached data
--refresh-package
refresh-packageRefresh cached data for a specific package
--reinstall
Reinstall all packages, regardless of whether they’re already installed. Implies
--refresh
--reinstall-package
reinstall-packageReinstall a specific package, regardless of whether it’s already installed. Implies
--refresh-package
--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script
scriptRemove the dependency from the specified Python script, rather than from a project.
If provided, uv will remove the dependency from the script’s inline metadata table, in adherence with PEP 723.
--upgrade
,-U
Allow package upgrades, ignoring pinned versions in any existing output file. Implies
--refresh
--upgrade-package
,-P
upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies
--refresh-package
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv sync
Update the project's environment.
Syncing ensures that all project dependencies are installed and up-to-date with the lockfile.
By default, an exact sync is performed: uv removes packages that are not declared as dependencies of the project. Use the --inexact
flag to keep extraneous packages. Note that if an extraneous package conflicts with a project dependency, it will still be removed. Additionally, if --no-build-isolation
is used, uv will not remove extraneous packages to avoid removing possible build dependencies.
If the project virtual environment (.venv
) does not exist, it will be created.
The project is re-locked before syncing unless the --locked
or --frozen
flag is provided.
uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.
Note that, when installing from a lockfile, uv will not provide warnings for yanked package versions.
Usage
Options
--all-extras
Include all optional dependencies.
When two or more extras are declared as conflicting in
tool.uv.conflicts
, using this flag will always result in an error.Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.
--all-groups
Include dependencies from all dependency groups.
--no-group
can be used to exclude specific groups.--all-packages
Sync all packages in the workspace.
The workspace’s environment (
.venv
) is updated to include all workspace members.Any extras or groups specified via
--extra
,--group
, or related options will be applied to all workspace members.--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--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.
May also be set with the
UV_COMPILE_BYTECODE
environment variable.--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra
extraInclude optional dependencies from the specified extra name.
May be provided more than once.
When multiple extras or groups are specified that appear in
tool.uv.conflicts
, uv will report an error.Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.
--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--frozen
Sync without updating the
uv.lock
file.Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the
pyproject.toml
includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.May also be set with the
UV_FROZEN
environment variable.--group
groupInclude dependencies from the specified dependency group.
When multiple extras or groups are specified that appear in
tool.uv.conflicts
, uv will report an error.May be provided multiple times.
--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--inexact
Do not remove extraneous packages present in the environment.
When enabled, uv will make the minimum necessary changes to satisfy the requirements. By default, syncing will remove any extraneous packages from the environment
--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--locked
Assert that the
uv.lock
will remain unchanged.Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the
UV_LOCKED
environment variable.--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--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.
--no-binary-package
no-binary-packageDon’t install pre-built wheels for a specific package
--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.
--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-build-package
no-build-packageDon’t build source distributions for a specific package
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-dev
Omit the development dependency group.
This option is an alias for
--no-group dev
.--no-editable
Install any editable dependencies, including the project and any workspace members, as non-editable
--no-extra
no-extraExclude the specified optional dependencies, if
--all-extras
is supplied.May be provided multiple times.
--no-group
no-groupExclude dependencies from the specified dependency group.
May be provided multiple times.
--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-install-package
no-install-packageDo not install the given package(s).
By default, all of the project’s dependencies are installed into the environment. The
--no-install-package
option allows exclusion of specific packages. Note this can result in a broken environment, and should be used with caution.--no-install-project
Do not install the current project.
By default, the current project is installed into the environment with all of its dependencies. The
--no-install-project
option allows the project to be excluded, but all of its dependencies are still installed. This is particularly useful in situations like building Docker images where installing the project separately from its dependencies allows optimal layer caching.--no-install-workspace
Do not install any workspace members, including the root project.
By default, all of the workspace members and their dependencies are installed into the environment. The
--no-install-workspace
option allows exclusion of all the workspace members while retaining their dependencies. This is particularly useful in situations like building Docker images where installing the workspace separately from its dependencies allows optimal layer caching.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--only-dev
Only include the development dependency group.
Omit other dependencies. The project itself will also be omitted.
This option is an alias for
--only-group dev
.--only-group
only-groupOnly include dependencies from the specified dependency group.
May be provided multiple times.
The project itself will also be omitted.
--package
packageSync for a specific package in the workspace.
The workspace’s environment (
.venv
) is updated to reflect the subset of dependencies declared by the specified workspace member package.If the workspace member does not exist, uv will exit with an error.
--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter to use for the project environment.
By default, the first interpreter that meets the project’s
requires-python
constraint is used.If a Python interpreter in a virtual environment is provided, the packages will not be synced to the given environment. The interpreter will be used to create a virtual environment in the project.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--refresh
Refresh all cached data
--refresh-package
refresh-packageRefresh cached data for a specific package
--reinstall
Reinstall all packages, regardless of whether they’re already installed. Implies
--refresh
--reinstall-package
reinstall-packageReinstall a specific package, regardless of whether it’s already installed. Implies
--refresh-package
--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--upgrade
,-U
Allow package upgrades, ignoring pinned versions in any existing output file. Implies
--refresh
--upgrade-package
,-P
upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies
--refresh-package
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv lock
Update the project's lockfile.
If the project lockfile (uv.lock
) does not exist, it will be created. If a lockfile is present, its contents will be used as preferences for the resolution.
If there are no changes to the project's dependencies, locking will have no effect unless the --upgrade
flag is provided.
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--dry-run
Perform a dry run, without writing the lockfile.
In dry-run mode, uv will resolve the project’s dependencies and report on the resulting changes, but will not write the lockfile to disk.
--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--frozen
Assert that a
uv.lock
exists, without updating itMay also be set with the
UV_FROZEN
environment variable.--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
This option is only used when building source distributions.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--locked
Assert that the
uv.lock
will remain unchanged.Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the
UV_LOCKED
environment variable.--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--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.
--no-binary-package
no-binary-packageDon’t install pre-built wheels for a specific package
--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.
--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-build-package
no-build-packageDon’t build source distributions for a specific package
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter to use during resolution.
A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.
The interpreter is also used as the fallback value for the minimum Python version if
requires-python
is not set.See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--refresh
Refresh all cached data
--refresh-package
refresh-packageRefresh cached data for a specific package
--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--upgrade
,-U
Allow package upgrades, ignoring pinned versions in any existing output file. Implies
--refresh
--upgrade-package
,-P
upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies
--refresh-package
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv export
Export the project's lockfile to an alternate format.
At present, only requirements-txt
is supported.
The project is re-locked before exporting unless the --locked
or --frozen
flag is provided.
uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.
If operating in a workspace, the root will be exported by default; however, a specific member can be selected using the --package
option.
Usage
Options
--all-extras
Include all optional dependencies
--all-groups
Include dependencies from all dependency groups.
--no-group
can be used to exclude specific groups.--all-packages
Export the entire workspace.
The dependencies for all workspace members will be included in the exported requirements file.
Any extras or groups specified via
--extra
,--group
, or related options will be applied to all workspace members.--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra
extraInclude optional dependencies from the specified extra name.
May be provided more than once.
--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--format
formatThe format to which
uv.lock
should be exported.At present, only
requirements-txt
is supported.[default: requirements-txt]
Possible values:
requirements-txt
: Export inrequirements.txt
format
--frozen
Do not update the
uv.lock
before exporting.If a
uv.lock
does not exist, uv will exit with an error.May also be set with the
UV_FROZEN
environment variable.--group
groupInclude dependencies from the specified dependency group.
May be provided multiple times.
--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
This option is only used when building source distributions.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--locked
Assert that the
uv.lock
will remain unchanged.Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the
UV_LOCKED
environment variable.--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--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.
--no-binary-package
no-binary-packageDon’t install pre-built wheels for a specific package
--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.
--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-build-package
no-build-packageDon’t build source distributions for a specific package
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-dev
Omit the development dependency group.
This option is an alias for
--no-group dev
.--no-editable
Install any editable dependencies, including the project and any workspace members, as non-editable
--no-emit-package
no-emit-packageDo not emit the given package(s).
By default, all of the project’s dependencies are included in the exported requirements file. The
--no-install-package
option allows exclusion of specific packages.--no-emit-project
Do not emit the current project.
By default, the current project is included in the exported requirements file with all of its dependencies. The
--no-emit-project
option allows the project to be excluded, but all of its dependencies to remain included.--no-emit-workspace
Do not emit any workspace members, including the root project.
By default, all workspace members and their dependencies are included in the exported requirements file, with all of their dependencies. The
--no-emit-workspace
option allows exclusion of all the workspace members while retaining their dependencies.--no-extra
no-extraExclude the specified optional dependencies, if
--all-extras
is supplied.May be provided multiple times.
--no-group
no-groupExclude dependencies from the specified dependency group.
May be provided multiple times.
--no-hashes
Omit hashes in the generated output
--no-header
Exclude the comment header at the top of the generated output file
--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--only-dev
Only include the development dependency group.
Omit other dependencies. The project itself will also be omitted.
This option is an alias for
--only-group dev
.--only-group
only-groupOnly include dependencies from the specified dependency group.
May be provided multiple times.
The project itself will also be omitted.
--output-file
,-o
output-fileWrite the exported requirements to the given file
--package
packageExport the dependencies for a specific package in the workspace.
If the workspace member does not exist, uv will exit with an error.
--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--prune
prunePrune the given package from the dependency tree.
Pruned packages will be excluded from the exported requirements file, as will any dependencies that are no longer required after the pruned package is removed.
--python
,-p
pythonThe Python interpreter to use during resolution.
A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.
The interpreter is also used as the fallback value for the minimum Python version if
requires-python
is not set.See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--refresh
Refresh all cached data
--refresh-package
refresh-packageRefresh cached data for a specific package
--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--upgrade
,-U
Allow package upgrades, ignoring pinned versions in any existing output file. Implies
--refresh
--upgrade-package
,-P
upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies
--refresh-package
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv tree
Display the project's dependency tree
Usage
Options
--all-groups
Include dependencies from all dependency groups.
--no-group
can be used to exclude specific groups.--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--depth
,-d
depthMaximum display depth of the dependency tree
[default: 255]
--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--frozen
Display the requirements without locking the project.
If the lockfile is missing, uv will exit with an error.
May also be set with the
UV_FROZEN
environment variable.--group
groupInclude dependencies from the specified dependency group.
May be provided multiple times.
--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--invert
Show the reverse dependencies for the given package. This flag will invert the tree and display the packages that depend on the given package
--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
This option is only used when building source distributions.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--locked
Assert that the
uv.lock
will remain unchanged.Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the
UV_LOCKED
environment variable.--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--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.
--no-binary-package
no-binary-packageDon’t install pre-built wheels for a specific package
--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.
--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-build-package
no-build-packageDon’t build source distributions for a specific package
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-dedupe
Do not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its dependencies, and will include a (*) to indicate it has already been shown. This flag will cause those duplicates to be repeated
--no-dev
Omit the development dependency group.
This option is an alias for
--no-group dev
.--no-group
no-groupExclude dependencies from the specified dependency group.
May be provided multiple times.
--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--only-dev
Only include the development dependency group.
Omit other dependencies. The project itself will also be omitted.
This option is an alias for
--only-group dev
.--only-group
only-groupOnly include dependencies from the specified dependency group.
May be provided multiple times.
The project itself will also be omitted.
--outdated
Show the latest available version of each package in the tree
--package
packageDisplay only the specified packages
--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--prune
prunePrune the given package from the display of the dependency tree
--python
,-p
pythonThe Python interpreter to use for locking and filtering.
By default, the tree is filtered to match the platform as reported by the Python interpreter. Use
--universal
to display the tree for all platforms, or use--python-version
or--python-platform
to override a subset of markers.See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-platform
python-platformThe platform to use when filtering the tree.
For example, pass
--platform windows
to display the dependencies that would be included when installing on Windows.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
oraarch64-apple-darwin
.Possible values:
windows
: An alias forx86_64-pc-windows-msvc
, the default target for Windowslinux
: An alias forx86_64-unknown-linux-gnu
, the default target for Linuxmacos
: An alias foraarch64-apple-darwin
, the default target for macOSx86_64-pc-windows-msvc
: A 64-bit x86 Windows targeti686-pc-windows-msvc
: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu
: An x86 Linux target. Equivalent tox86_64-manylinux_2_17
aarch64-apple-darwin
: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin
: An x86 macOS targetaarch64-unknown-linux-gnu
: An ARM64 Linux target. Equivalent toaarch64-manylinux_2_17
aarch64-unknown-linux-musl
: An ARM64 Linux targetx86_64-unknown-linux-musl
: Anx86_64
Linux targetx86_64-manylinux_2_17
: Anx86_64
target for themanylinux_2_17
platformx86_64-manylinux_2_28
: Anx86_64
target for themanylinux_2_28
platformx86_64-manylinux_2_31
: Anx86_64
target for themanylinux_2_31
platformx86_64-manylinux_2_32
: Anx86_64
target for themanylinux_2_32
platformx86_64-manylinux_2_33
: Anx86_64
target for themanylinux_2_33
platformx86_64-manylinux_2_34
: Anx86_64
target for themanylinux_2_34
platformx86_64-manylinux_2_35
: Anx86_64
target for themanylinux_2_35
platformx86_64-manylinux_2_36
: Anx86_64
target for themanylinux_2_36
platformx86_64-manylinux_2_37
: Anx86_64
target for themanylinux_2_37
platformx86_64-manylinux_2_38
: Anx86_64
target for themanylinux_2_38
platformx86_64-manylinux_2_39
: Anx86_64
target for themanylinux_2_39
platformx86_64-manylinux_2_40
: Anx86_64
target for themanylinux_2_40
platformaarch64-manylinux_2_17
: An ARM64 target for themanylinux_2_17
platformaarch64-manylinux_2_28
: An ARM64 target for themanylinux_2_28
platformaarch64-manylinux_2_31
: An ARM64 target for themanylinux_2_31
platformaarch64-manylinux_2_32
: An ARM64 target for themanylinux_2_32
platformaarch64-manylinux_2_33
: An ARM64 target for themanylinux_2_33
platformaarch64-manylinux_2_34
: An ARM64 target for themanylinux_2_34
platformaarch64-manylinux_2_35
: An ARM64 target for themanylinux_2_35
platformaarch64-manylinux_2_36
: An ARM64 target for themanylinux_2_36
platformaarch64-manylinux_2_37
: An ARM64 target for themanylinux_2_37
platformaarch64-manylinux_2_38
: An ARM64 target for themanylinux_2_38
platformaarch64-manylinux_2_39
: An ARM64 target for themanylinux_2_39
platformaarch64-manylinux_2_40
: An ARM64 target for themanylinux_2_40
platform
--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--python-version
python-versionThe Python version to use when filtering the tree.
For example, pass
--python-version 3.10
to display the dependencies that would be included when installing on Python 3.10.Defaults to the version of the discovered Python interpreter.
--quiet
,-q
Do not print any output
--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--universal
Show a platform-independent dependency tree.
Shows resolved package versions for all Python versions and platforms, rather than filtering to those that are relevant for the current environment.
Multiple versions may be shown for a each package.
--upgrade
,-U
Allow package upgrades, ignoring pinned versions in any existing output file. Implies
--refresh
--upgrade-package
,-P
upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies
--refresh-package
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv tool
Run and install commands provided by Python packages
Usage
Commands
uv tool run
Run a command provided by a Python package
uv tool install
Install commands provided by a Python package
uv tool upgrade
Upgrade installed tools
uv tool list
List installed tools
uv tool uninstall
Uninstall a tool
uv tool update-shell
Ensure that the tool executable directory is on the
PATH
uv tool dir
Show the path to the uv tools directory
uv tool run
Run a command provided by a Python package.
By default, the package to install is assumed to match the command name.
The name of the command can include an exact version in the format <package>@<version>
, e.g., uv tool run [email protected]
. If more complex version specification is desired or if the command is provided by a different package, use --from
.
If the tool was previously installed, i.e., via uv tool install
, the installed version will be used unless a version is requested or the --isolated
flag is used.
uvx
is provided as a convenient alias for uv tool run
, their behavior is identical.
If no command is provided, the installed tools are displayed.
Packages are installed into an ephemeral virtual environment in the uv cache directory.
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--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.
May also be set with the
UV_COMPILE_BYTECODE
environment variable.--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--from
fromUse the given package to provide the command.
By default, the package name is assumed to match the command name.
--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--isolated
Run the tool in an isolated virtual environment, ignoring any already-installed tools
--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--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.
--no-binary-package
no-binary-packageDon’t install pre-built wheels for a specific package
--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.
--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-build-package
no-build-packageDon’t build source distributions for a specific package
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter to use to build the run environment.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--refresh
Refresh all cached data
--refresh-package
refresh-packageRefresh cached data for a specific package
--reinstall
Reinstall all packages, regardless of whether they’re already installed. Implies
--refresh
--reinstall-package
reinstall-packageReinstall a specific package, regardless of whether it’s already installed. Implies
--refresh-package
--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--upgrade
,-U
Allow package upgrades, ignoring pinned versions in any existing output file. Implies
--refresh
--upgrade-package
,-P
upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies
--refresh-package
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
--with
withRun with the given packages installed
--with-editable
with-editableRun with the given packages installed as editables
When used in a project, these dependencies will be layered on top of the uv tool’s environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified.
--with-requirements
with-requirementsRun with all packages listed in the given
requirements.txt
files
uv tool install
Install commands provided by a Python package.
Packages are installed into an isolated virtual environment in the uv tools directory. The executables are linked the tool executable directory, which is determined according to the XDG standard and can be retrieved with uv tool dir --bin
.
If the tool was previously installed, the existing tool will generally be replaced.
Usage
Arguments
PACKAGE
The package to install commands from
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--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.
May also be set with the
UV_COMPILE_BYTECODE
environment variable.--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--constraints
,-c
constraintsConstrain versions using the given requirements files.
Constraints files are
requirements.txt
-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.This is equivalent to pip’s
--constraint
option.May also be set with the
UV_CONSTRAINT
environment variable.--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--editable
,-e
--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--force
Force installation of the tool.
Will replace any existing entry points with the same name in the executable directory.
--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--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.
--no-binary-package
no-binary-packageDon’t install pre-built wheels for a specific package
--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.
--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-build-package
no-build-packageDon’t build source distributions for a specific package
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--overrides
overridesOverride versions using the given requirements files.
Overrides files are
requirements.txt
-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered 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 the constituent packages.
May also be set with the
UV_OVERRIDE
environment variable.--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter to use to build the tool environment.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--refresh
Refresh all cached data
--refresh-package
refresh-packageRefresh cached data for a specific package
--reinstall
Reinstall all packages, regardless of whether they’re already installed. Implies
--refresh
--reinstall-package
reinstall-packageReinstall a specific package, regardless of whether it’s already installed. Implies
--refresh-package
--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--upgrade
,-U
Allow package upgrades, ignoring pinned versions in any existing output file. Implies
--refresh
--upgrade-package
,-P
upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies
--refresh-package
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
--with
withInclude the following extra requirements
--with-editable
with-editableInclude the given packages as editables
--with-requirements
with-requirementsRun all requirements listed in the given
requirements.txt
files
uv tool upgrade
Upgrade installed tools.
If a tool was installed with version constraints, they will be respected on upgrade — to upgrade a tool beyond the originally provided constraints, use uv tool install
again.
If a tool was installed with specific settings, they will be respected on upgraded. For example, if --prereleases allow
was provided during installation, it will continue to be respected in upgrades.
Usage
Arguments
NAME
The name of the tool to upgrade, along with an optional version specifier
Options
--all
Upgrade all tools
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--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.
May also be set with the
UV_COMPILE_BYTECODE
environment variable.--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--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.
--no-binary-package
no-binary-packageDon’t install pre-built wheels for a specific package
--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.
--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-build-package
no-build-packageDon’t build source distributions for a specific package
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonUpgrade a tool, and specify it to use the given Python interpreter to build its environment. Use with
--all
to apply to all tools.See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--reinstall
Reinstall all packages, regardless of whether they’re already installed. Implies
--refresh
--reinstall-package
reinstall-packageReinstall a specific package, regardless of whether it’s already installed. Implies
--refresh-package
--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv tool list
List installed tools
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--quiet
,-q
Do not print any output
--show-paths
Whether to display the path to each tool environment and installed executable
--show-version-specifiers
Whether to display the version specifier(s) used to install each tool
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv tool uninstall
Uninstall a tool
Usage
Arguments
NAME
The name of the tool to uninstall
Options
--all
Uninstall all tools
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv tool update-shell
Ensure that the tool executable directory is on the PATH
.
If the tool executable directory is not present on the PATH
, uv will attempt to add it to the relevant shell configuration files.
If the shell configuration files already include a blurb to add the executable directory to the path, but the directory is not present on the PATH
, uv will exit with an error.
The tool executable directory is determined according to the XDG standard and can be retrieved with uv tool dir --bin
.
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv tool dir
Show the path to the uv tools directory.
The tools directory is used to store environments and metadata for installed tools.
By default, tools are stored in the uv data directory at $XDG_DATA_HOME/uv/tools
or $HOME/.local/share/uv/tools
on Unix and %APPDATA%\uv\data\tools
on Windows.
The tool installation directory may be overridden with $UV_TOOL_DIR
.
To instead view the directory uv installs executables into, use the --bin
flag.
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--bin
Show the directory into which
uv tool
will install executables.By default,
uv tool dir
shows the directory into which the tool Python environments themselves are installed, rather than the directory containing the linked executables.The tool executable directory is determined according to the XDG standard and is derived from the following environment variables, in order of preference:
$UV_TOOL_BIN_DIR
$XDG_BIN_HOME
$XDG_DATA_HOME/../bin
$HOME/.local/bin
--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv python
Manage Python versions and installations
Generally, uv first searches for Python in a virtual environment, either active or in a
.venv
directory in the current working directory or any parent directory. If a virtual
environment is not required, uv will then search for a Python interpreter. Python
interpreters are found by searching for Python executables in the PATH
environment
variable.
On Windows, the registry is also searched for Python executables.
By default, uv will download Python if a version cannot be found. This behavior can be
disabled with the --no-python-downloads
flag or the python-downloads
setting.
The --python
option allows requesting a different interpreter.
The following Python version request formats are supported:
<version>
e.g.3
,3.12
,3.12.3
<version-specifier>
e.g.>=3.12,<3.13
<implementation>
e.g.cpython
orcp
<implementation>@<version>
e.g.[email protected]
<implementation><version>
e.g.cpython3.12
orcp312
<implementation><version-specifier>
e.g.cpython>=3.12,<3.13
<implementation>-<version>-<os>-<arch>-<libc>
e.g.cpython-3.12.3-macos-aarch64-none
Additionally, a specific system Python interpreter can often be requested with:
<executable-path>
e.g./opt/homebrew/bin/python3
<executable-name>
e.g.mypython3
<install-dir>
e.g./some/environment/
When the --python
option is used, normal discovery rules apply but discovered interpreters
are checked for compatibility with the request, e.g., if pypy
is requested, uv will first
check if the virtual environment contains a PyPy interpreter then check if each executable
in the path is a PyPy interpreter.
uv supports discovering CPython, PyPy, and GraalPy interpreters. Unsupported interpreters will be skipped during discovery. If an unsupported interpreter implementation is requested, uv will exit with an error.
Usage
Commands
uv python list
List the available Python installations
uv python install
Download and install Python versions
uv python find
Search for a Python installation
uv python pin
Pin to a specific Python version
uv python dir
Show the uv Python installation directory
uv python uninstall
Uninstall Python versions
uv python list
List the available Python installations.
By default, installed Python versions and the downloads for latest available patch version of each supported Python major version are shown.
The displayed versions are filtered by the --python-preference
option, i.e., if using only-system
, no managed Python versions will be shown.
Use --all-versions
to view all available patch versions.
Use --only-installed
to omit available downloads.
Usage
Options
--all-platforms
List Python downloads for all platforms.
By default, only downloads for the current platform are shown.
--all-versions
List all Python versions, including old patch versions.
By default, only the latest patch version is shown for each minor version.
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--only-installed
Only show installed Python versions, exclude available downloads.
By default, available downloads for the current platform are shown.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv python install
Download and install Python versions.
Multiple Python versions may be requested.
Supports CPython and PyPy. CPython distributions are downloaded from the python-build-standalone
project. PyPy distributions are downloaded from python.org
.
Python versions are installed into the uv Python directory, which can be retrieved with uv python dir
.
A python
executable is not made globally available, managed Python versions are only used in uv commands or in active virtual environments. There is experimental support for adding Python executables to the PATH
— use the --preview
flag to enable this behavior.
See uv help python
to view supported request formats.
Usage
Arguments
TARGETS
The Python version(s) to install.
If not provided, the requested Python version(s) will be read from the
.python-versions
or.python-version
files. If neither file is present, uv will check if it has installed any Python versions. If not, it will install the latest stable version of Python.See uv python to view supported request formats.
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--default
Use as the default Python version.
By default, only a
python{major}.{minor}
executable is installed, e.g.,python3.10
. When the--default
flag is used,python{major}
, e.g.,python3
, andpython
executables are also installed.Alternative Python variants will still include their tag. For example, installing 3.13+freethreaded with
--default
will include inpython3t
andpythont
, notpython3
andpython
.If multiple Python versions are requested during the installation, the first request will be the default.
--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--force
,-f
Replace existing Python executables during installation.
By default, uv will refuse to replace executables that it does not manage.
Implies
--reinstall
.--help
,-h
Display the concise help for this command
--mirror
mirrorSet the URL to use as the source for downloading Python installations.
The provided URL will replace
https://github.com/indygreg/python-build-standalone/releases/download
in, e.g.,https://github.com/indygreg/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz
.Distributions can be read from a local directory by using the
file://
URL scheme.May also be set with the
UV_PYTHON_INSTALL_MIRROR
environment variable.--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--pypy-mirror
pypy-mirrorSet the URL to use as the source for downloading PyPy installations.
The provided URL will replace
https://downloads.python.org/pypy
in, e.g.,https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2
.Distributions can be read from a local directory by using the
file://
URL scheme.May also be set with the
UV_PYPY_INSTALL_MIRROR
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--reinstall
,-r
Reinstall the requested Python version, if it’s already installed.
By default, uv will exit successfully if the version is already installed.
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv python find
Search for a Python installation.
Displays the path to the Python executable.
See uv help python
to view supported request formats and details on discovery behavior.
Usage
Arguments
REQUEST
The Python request.
See uv python to view supported request formats.
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-project
Avoid discovering a project or workspace.
Otherwise, when no request is provided, the Python requirement of a project in the current directory or parent directories will be used.
--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--system
Only find system Python interpreters.
By default, uv will report the first Python interpreter it would use, including those in an active virtual environment or a virtual environment in the current working directory or any parent directory.
The
--system
option instructs uv to skip virtual environment Python interpreters and restrict its search to the system path.May also be set with the
UV_SYSTEM_PYTHON
environment variable.--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv python pin
Pin to a specific Python version.
Writes the pinned Python version to a .python-version
file, which is used by other uv commands to determine the required Python version.
If no version is provided, uv will look for an existing .python-version
file and display the currently pinned version. If no .python-version
file is found, uv will exit with an error.
See uv help python
to view supported request formats.
Usage
Arguments
REQUEST
The Python version request.
uv supports more formats than other tools that read
.python-version
files, i.e.,pyenv
. If compatibility with those tools is needed, only use version numbers instead of complex requests such as[email protected]
.If no request is provided, the currently pinned version will be shown.
See uv python to view supported request formats.
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-project
Avoid validating the Python pin is compatible with the project or workspace.
By default, a project or workspace is discovered in the current directory or any parent directory. If a workspace is found, the Python pin is validated against the workspace’s
requires-python
constraint.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--resolved
Write the resolved Python interpreter path instead of the request.
Ensures that the exact same interpreter is used.
This option is usually not safe to use when committing the
.python-version
file to version control.--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv python dir
Show the uv Python installation directory.
By default, Python installations are stored in the uv data directory at $XDG_DATA_HOME/uv/python
or $HOME/.local/share/uv/python
on Unix and %APPDATA%\uv\data\python
on Windows.
The Python installation directory may be overridden with $UV_PYTHON_INSTALL_DIR
.
To view the directory where uv installs Python executables instead, use the --bin
flag. Note that Python executables are only installed when preview mode is enabled.
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--bin
Show the directory into which
uv python
will install Python executables.Note that this directory is only used when installing Python with preview mode enabled.
The Python executable directory is determined according to the XDG standard and is derived from the following environment variables, in order of preference:
$UV_PYTHON_BIN_DIR
$XDG_BIN_HOME
$XDG_DATA_HOME/../bin
$HOME/.local/bin
--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv python uninstall
Uninstall Python versions
Usage
Arguments
TARGETS
The Python version(s) to uninstall.
See uv python to view supported request formats.
Options
--all
Uninstall all managed Python versions
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv pip
Manage Python packages with a pip-compatible interface
Usage
Commands
uv pip compile
Compile a
requirements.in
file to arequirements.txt
fileuv pip sync
Sync an environment with a
requirements.txt
fileuv pip install
Install packages into an environment
uv pip uninstall
Uninstall packages from an environment
uv pip freeze
List, in requirements format, packages installed in an environment
uv pip list
List, in tabular format, packages installed in an environment
uv pip show
Show information about one or more installed packages
uv pip tree
Display the dependency tree for an environment
uv pip check
Verify installed packages have compatible dependencies
uv pip compile
Compile a requirements.in
file to a requirements.txt
file
Usage
Arguments
SRC_FILE
Include all packages listed in the given
requirements.in
files.If a
pyproject.toml
,setup.py
, orsetup.cfg
file is provided, uv will extract the requirements for the relevant project.If
-
is provided, then requirements will be read from stdin.The order of the requirements files and the requirements in them is used to determine priority during resolution.
Options
--all-extras
Include all optional dependencies.
Only applies to
pyproject.toml
,setup.py
, andsetup.cfg
sources.--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--annotation-style
annotation-styleThe style of the annotation comments included in the output file, used to indicate the source of each package.
Defaults to
split
.Possible values:
line
: Render the annotations on a single, comma-separated linesplit
: Render each annotation on its own line
--build-constraints
,-b
build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
Constraints files are
requirements.txt
-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.May also be set with the
UV_BUILD_CONSTRAINT
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--constraints
,-c
constraintsConstrain versions using the given requirements files.
Constraints files are
requirements.txt
-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.This is equivalent to pip’s
--constraint
option.May also be set with the
UV_CONSTRAINT
environment variable.--custom-compile-command
custom-compile-commandThe 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
.May also be set with the
UV_CUSTOM_COMPILE_COMMAND
environment variable.--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--emit-build-options
Include
--no-binary
and--only-binary
entries in the generated output file--emit-find-links
Include
--find-links
entries in the generated output file--emit-index-annotation
Include comment annotations indicating the index used to resolve each package (e.g.,
# from https://pypi.org/simple
)--emit-index-url
Include
--index-url
and--extra-index-url
entries in the generated output file--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra
extraInclude optional dependencies from the specified extra name; may be provided more than once.
Only applies to
pyproject.toml
,setup.py
, andsetup.cfg
sources.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--generate-hashes
Include distribution hashes in the output file
--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
This option is only used when building source distributions.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-annotate
Exclude comment annotations indicating the source of each package
--no-binary
no-binaryDon’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:
.--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:
.--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-deps
Ignore package dependencies, instead only add those packages explicitly listed on the command line to the resulting the requirements file
--no-emit-package
no-emit-packageSpecify 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--no-header
Exclude the comment header at the top of the generated output file
--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--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 ininstall
andsync
invocations.--no-strip-markers
Include environment markers in the output file.
By default, uv strips environment markers, as the resolution generated by
compile
is only guaranteed to be correct for the target environment.--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--only-binary
only-binaryOnly 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:
.--output-file
,-o
output-fileWrite the compiled requirements 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.--overrides
overridesOverride versions using the given requirements files.
Overrides files are
requirements.txt
-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered 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 the constituent packages.
May also be set with the
UV_OVERRIDE
environment variable.--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
pythonThe Python interpreter to use during resolution.
A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.
The interpreter is also used to determine the default minimum Python version, unless
--python-version
is provided.See uv python for details on Python discovery and supported request formats.
--python-platform
python-platformThe 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
oraarch64-apple-darwin
.Possible values:
windows
: An alias forx86_64-pc-windows-msvc
, the default target for Windowslinux
: An alias forx86_64-unknown-linux-gnu
, the default target for Linuxmacos
: An alias foraarch64-apple-darwin
, the default target for macOSx86_64-pc-windows-msvc
: A 64-bit x86 Windows targeti686-pc-windows-msvc
: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu
: An x86 Linux target. Equivalent tox86_64-manylinux_2_17
aarch64-apple-darwin
: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin
: An x86 macOS targetaarch64-unknown-linux-gnu
: An ARM64 Linux target. Equivalent toaarch64-manylinux_2_17
aarch64-unknown-linux-musl
: An ARM64 Linux targetx86_64-unknown-linux-musl
: Anx86_64
Linux targetx86_64-manylinux_2_17
: Anx86_64
target for themanylinux_2_17
platformx86_64-manylinux_2_28
: Anx86_64
target for themanylinux_2_28
platformx86_64-manylinux_2_31
: Anx86_64
target for themanylinux_2_31
platformx86_64-manylinux_2_32
: Anx86_64
target for themanylinux_2_32
platformx86_64-manylinux_2_33
: Anx86_64
target for themanylinux_2_33
platformx86_64-manylinux_2_34
: Anx86_64
target for themanylinux_2_34
platformx86_64-manylinux_2_35
: Anx86_64
target for themanylinux_2_35
platformx86_64-manylinux_2_36
: Anx86_64
target for themanylinux_2_36
platformx86_64-manylinux_2_37
: Anx86_64
target for themanylinux_2_37
platformx86_64-manylinux_2_38
: Anx86_64
target for themanylinux_2_38
platformx86_64-manylinux_2_39
: Anx86_64
target for themanylinux_2_39
platformx86_64-manylinux_2_40
: Anx86_64
target for themanylinux_2_40
platformaarch64-manylinux_2_17
: An ARM64 target for themanylinux_2_17
platformaarch64-manylinux_2_28
: An ARM64 target for themanylinux_2_28
platformaarch64-manylinux_2_31
: An ARM64 target for themanylinux_2_31
platformaarch64-manylinux_2_32
: An ARM64 target for themanylinux_2_32
platformaarch64-manylinux_2_33
: An ARM64 target for themanylinux_2_33
platformaarch64-manylinux_2_34
: An ARM64 target for themanylinux_2_34
platformaarch64-manylinux_2_35
: An ARM64 target for themanylinux_2_35
platformaarch64-manylinux_2_36
: An ARM64 target for themanylinux_2_36
platformaarch64-manylinux_2_37
: An ARM64 target for themanylinux_2_37
platformaarch64-manylinux_2_38
: An ARM64 target for themanylinux_2_38
platformaarch64-manylinux_2_39
: An ARM64 target for themanylinux_2_39
platformaarch64-manylinux_2_40
: An ARM64 target for themanylinux_2_40
platform
--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--python-version
,-p
python-versionThe Python version to use for resolution.
For example,
3.8
or3.8.17
.Defaults to the version of the Python interpreter used for resolution.
Defines the minimum Python version that must be supported by the resolved requirements.
If a patch version is omitted, the minimum patch version is assumed. For example,
3.8
is mapped to3.8.0
.--quiet
,-q
Do not print any output
--refresh
Refresh all cached data
--refresh-package
refresh-packageRefresh cached data for a specific package
--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--system
Install packages into the system Python environment.
By default, uv uses the virtual environment in the current working directory or any parent directory, falling back to searching for a Python executable in
PATH
. The--system
option instructs uv to avoid using a virtual environment Python and restrict its search to the system path.May also be set with the
UV_SYSTEM_PYTHON
environment variable.--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.Implies
--no-strip-markers
.--upgrade
,-U
Allow package upgrades, ignoring pinned versions in any existing output file. Implies
--refresh
--upgrade-package
,-P
upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies
--refresh-package
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv pip sync
Sync an environment with a requirements.txt
file
Usage
Arguments
SRC_FILE
Include all packages listed in the given
requirements.txt
files.If a
pyproject.toml
,setup.py
, orsetup.cfg
file is provided, uv will extract the requirements for the relevant project.If
-
is provided, then requirements will be read from stdin.
Options
--allow-empty-requirements
Allow sync of empty requirements, which will clear the environment of all packages
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--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, likeapt
. It should be used with caution, as such Python installations explicitly recommend against modifications by other package managers (like uv orpip
).May also be set with the
UV_BREAK_SYSTEM_PACKAGES
environment variable.--build-constraints
,-b
build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
Constraints files are
requirements.txt
-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.May also be set with the
UV_BUILD_CONSTRAINT
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--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.
May also be set with the
UV_COMPILE_BYTECODE
environment variable.--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--constraints
,-c
constraintsConstrain versions using the given requirements files.
Constraints files are
requirements.txt
-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.This is equivalent to pip’s
--constraint
option.May also be set with the
UV_CONSTRAINT
environment variable.--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--dry-run
Perform a dry run, i.e., don’t actually install anything but resolve the dependencies and print the resulting plan
--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-allow-empty-requirements
--no-binary
no-binaryDon’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:
.--no-break-system-packages
--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:
.--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--no-verify-hashes
Disable validation of hashes in the requirements file.
By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use
--require-hashes
.May also be set with the
UV_NO_VERIFY_HASHES
environment variable.--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--only-binary
only-binaryOnly 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:
.--prefix
prefixInstall 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.--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter into which packages should be installed.
By default, syncing requires a virtual environment. A path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-platform
python-platformThe platform for which requirements should be installed.
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
oraarch64-apple-darwin
.WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The
--python-platform
option is intended for advanced use cases.Possible values:
windows
: An alias forx86_64-pc-windows-msvc
, the default target for Windowslinux
: An alias forx86_64-unknown-linux-gnu
, the default target for Linuxmacos
: An alias foraarch64-apple-darwin
, the default target for macOSx86_64-pc-windows-msvc
: A 64-bit x86 Windows targeti686-pc-windows-msvc
: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu
: An x86 Linux target. Equivalent tox86_64-manylinux_2_17
aarch64-apple-darwin
: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin
: An x86 macOS targetaarch64-unknown-linux-gnu
: An ARM64 Linux target. Equivalent toaarch64-manylinux_2_17
aarch64-unknown-linux-musl
: An ARM64 Linux targetx86_64-unknown-linux-musl
: Anx86_64
Linux targetx86_64-manylinux_2_17
: Anx86_64
target for themanylinux_2_17
platformx86_64-manylinux_2_28
: Anx86_64
target for themanylinux_2_28
platformx86_64-manylinux_2_31
: Anx86_64
target for themanylinux_2_31
platformx86_64-manylinux_2_32
: Anx86_64
target for themanylinux_2_32
platformx86_64-manylinux_2_33
: Anx86_64
target for themanylinux_2_33
platformx86_64-manylinux_2_34
: Anx86_64
target for themanylinux_2_34
platformx86_64-manylinux_2_35
: Anx86_64
target for themanylinux_2_35
platformx86_64-manylinux_2_36
: Anx86_64
target for themanylinux_2_36
platformx86_64-manylinux_2_37
: Anx86_64
target for themanylinux_2_37
platformx86_64-manylinux_2_38
: Anx86_64
target for themanylinux_2_38
platformx86_64-manylinux_2_39
: Anx86_64
target for themanylinux_2_39
platformx86_64-manylinux_2_40
: Anx86_64
target for themanylinux_2_40
platformaarch64-manylinux_2_17
: An ARM64 target for themanylinux_2_17
platformaarch64-manylinux_2_28
: An ARM64 target for themanylinux_2_28
platformaarch64-manylinux_2_31
: An ARM64 target for themanylinux_2_31
platformaarch64-manylinux_2_32
: An ARM64 target for themanylinux_2_32
platformaarch64-manylinux_2_33
: An ARM64 target for themanylinux_2_33
platformaarch64-manylinux_2_34
: An ARM64 target for themanylinux_2_34
platformaarch64-manylinux_2_35
: An ARM64 target for themanylinux_2_35
platformaarch64-manylinux_2_36
: An ARM64 target for themanylinux_2_36
platformaarch64-manylinux_2_37
: An ARM64 target for themanylinux_2_37
platformaarch64-manylinux_2_38
: An ARM64 target for themanylinux_2_38
platformaarch64-manylinux_2_39
: An ARM64 target for themanylinux_2_39
platformaarch64-manylinux_2_40
: An ARM64 target for themanylinux_2_40
platform
--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--python-version
python-versionThe minimum Python version that should be supported by the requirements (e.g.,
3.7
or3.7.9
).If a patch version is omitted, the minimum patch version is assumed. For example,
3.7
is mapped to3.7.0
.--quiet
,-q
Do not print any output
--refresh
Refresh all cached data
--refresh-package
refresh-packageRefresh cached data for a specific package
--reinstall
Reinstall all packages, regardless of whether they’re already installed. Implies
--refresh
--reinstall-package
reinstall-packageReinstall a specific package, regardless of whether it’s already installed. Implies
--refresh-package
--require-hashes
Require a matching hash for each requirement.
By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash.
When
--require-hashes
is enabled, all requirements must include a hash or set of hashes, and 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.
May also be set with the
UV_REQUIRE_HASHES
environment variable.- Git dependencies are not supported. - Editable installs are not supported. - Local dependencies are not supported, unless they point to a specific wheel (
--strict
Validate the Python environment after completing the installation, to detect packages with missing dependencies or other issues
--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 systemPATH
.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.May also be set with the
UV_SYSTEM_PYTHON
environment variable.--target
targetInstall 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
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv pip install
Install packages into an environment
Usage
Arguments
PACKAGE
Install all listed packages.
The order of the packages is used to determine priority during resolution.
Options
--all-extras
Include all optional dependencies.
Only applies to
pyproject.toml
,setup.py
, andsetup.cfg
sources.--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--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, likeapt
. It should be used with caution, as such Python installations explicitly recommend against modifications by other package managers (like uv orpip
).May also be set with the
UV_BREAK_SYSTEM_PACKAGES
environment variable.--build-constraints
,-b
build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
Constraints files are
requirements.txt
-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.May also be set with the
UV_BUILD_CONSTRAINT
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--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.
May also be set with the
UV_COMPILE_BYTECODE
environment variable.--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--constraints
,-c
constraintsConstrain versions using the given requirements files.
Constraints files are
requirements.txt
-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.This is equivalent to pip’s
--constraint
option.May also be set with the
UV_CONSTRAINT
environment variable.--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--dry-run
Perform a dry run, i.e., don’t actually install anything but resolve the dependencies and print the resulting plan
--editable
,-e
editableInstall the editable package based on the provided local file path
--exact
Perform an exact sync, removing extraneous packages.
By default, installing will make the minimum necessary changes to satisfy the requirements. When enabled, uv will update the environment to exactly match the requirements, removing packages that are not included in the requirements.
--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra
extraInclude optional dependencies from the specified extra name; may be provided more than once.
Only applies to
pyproject.toml
,setup.py
, andsetup.cfg
sources.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-binary
no-binaryDon’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:
.--no-break-system-packages
--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:
.--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-deps
Ignore package dependencies, instead only installing those packages explicitly listed on the command line or in the requirements files
--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--no-verify-hashes
Disable validation of hashes in the requirements file.
By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use
--require-hashes
.May also be set with the
UV_NO_VERIFY_HASHES
environment variable.--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--only-binary
only-binaryOnly 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:
.--overrides
overridesOverride versions using the given requirements files.
Overrides files are
requirements.txt
-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered 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 the constituent packages.
May also be set with the
UV_OVERRIDE
environment variable.--prefix
prefixInstall 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.--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter into which packages should be installed.
By default, installation requires a virtual environment. A path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-platform
python-platformThe platform for which requirements should be installed.
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
oraarch64-apple-darwin
.WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The
--python-platform
option is intended for advanced use cases.Possible values:
windows
: An alias forx86_64-pc-windows-msvc
, the default target for Windowslinux
: An alias forx86_64-unknown-linux-gnu
, the default target for Linuxmacos
: An alias foraarch64-apple-darwin
, the default target for macOSx86_64-pc-windows-msvc
: A 64-bit x86 Windows targeti686-pc-windows-msvc
: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu
: An x86 Linux target. Equivalent tox86_64-manylinux_2_17
aarch64-apple-darwin
: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin
: An x86 macOS targetaarch64-unknown-linux-gnu
: An ARM64 Linux target. Equivalent toaarch64-manylinux_2_17
aarch64-unknown-linux-musl
: An ARM64 Linux targetx86_64-unknown-linux-musl
: Anx86_64
Linux targetx86_64-manylinux_2_17
: Anx86_64
target for themanylinux_2_17
platformx86_64-manylinux_2_28
: Anx86_64
target for themanylinux_2_28
platformx86_64-manylinux_2_31
: Anx86_64
target for themanylinux_2_31
platformx86_64-manylinux_2_32
: Anx86_64
target for themanylinux_2_32
platformx86_64-manylinux_2_33
: Anx86_64
target for themanylinux_2_33
platformx86_64-manylinux_2_34
: Anx86_64
target for themanylinux_2_34
platformx86_64-manylinux_2_35
: Anx86_64
target for themanylinux_2_35
platformx86_64-manylinux_2_36
: Anx86_64
target for themanylinux_2_36
platformx86_64-manylinux_2_37
: Anx86_64
target for themanylinux_2_37
platformx86_64-manylinux_2_38
: Anx86_64
target for themanylinux_2_38
platformx86_64-manylinux_2_39
: Anx86_64
target for themanylinux_2_39
platformx86_64-manylinux_2_40
: Anx86_64
target for themanylinux_2_40
platformaarch64-manylinux_2_17
: An ARM64 target for themanylinux_2_17
platformaarch64-manylinux_2_28
: An ARM64 target for themanylinux_2_28
platformaarch64-manylinux_2_31
: An ARM64 target for themanylinux_2_31
platformaarch64-manylinux_2_32
: An ARM64 target for themanylinux_2_32
platformaarch64-manylinux_2_33
: An ARM64 target for themanylinux_2_33
platformaarch64-manylinux_2_34
: An ARM64 target for themanylinux_2_34
platformaarch64-manylinux_2_35
: An ARM64 target for themanylinux_2_35
platformaarch64-manylinux_2_36
: An ARM64 target for themanylinux_2_36
platformaarch64-manylinux_2_37
: An ARM64 target for themanylinux_2_37
platformaarch64-manylinux_2_38
: An ARM64 target for themanylinux_2_38
platformaarch64-manylinux_2_39
: An ARM64 target for themanylinux_2_39
platformaarch64-manylinux_2_40
: An ARM64 target for themanylinux_2_40
platform
--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--python-version
python-versionThe minimum Python version that should be supported by the requirements (e.g.,
3.7
or3.7.9
).If a patch version is omitted, the minimum patch version is assumed. For example,
3.7
is mapped to3.7.0
.--quiet
,-q
Do not print any output
--refresh
Refresh all cached data
--refresh-package
refresh-packageRefresh cached data for a specific package
--reinstall
Reinstall all packages, regardless of whether they’re already installed. Implies
--refresh
--reinstall-package
reinstall-packageReinstall a specific package, regardless of whether it’s already installed. Implies
--refresh-package
--require-hashes
Require a matching hash for each requirement.
By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash.
When
--require-hashes
is enabled, all requirements must include a hash or set of hashes, and 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.
May also be set with the
UV_REQUIRE_HASHES
environment variable.- Git dependencies are not supported. - Editable installs are not supported. - Local dependencies are not supported, unless they point to a specific wheel (
--requirements
,-r
requirementsInstall all packages listed in the given
requirements.txt
files.If a
pyproject.toml
,setup.py
, orsetup.cfg
file is provided, uv will extract the requirements for the relevant project.If
-
is provided, then requirements will be read from stdin.--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--strict
Validate the Python environment after completing the installation, to detect packages with missing dependencies or other issues
--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 systemPATH
.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.May also be set with the
UV_SYSTEM_PYTHON
environment variable.--target
targetInstall 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
--upgrade
,-U
Allow package upgrades, ignoring pinned versions in any existing output file. Implies
--refresh
--upgrade-package
,-P
upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies
--refresh-package
--user
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv pip uninstall
Uninstall packages from an environment
Usage
Arguments
PACKAGE
Uninstall all listed packages
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--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, likeapt
. It should be used with caution, as such Python installations explicitly recommend against modifications by other package managers (like uv orpip
).May also be set with the
UV_BREAK_SYSTEM_PACKAGES
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--dry-run
Perform a dry run, i.e., don’t actually uninstall anything but print the resulting plan
--help
,-h
Display the concise help for this command
--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for remote requirements files.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-break-system-packages
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--prefix
prefixUninstall packages from the specified
--prefix
directory--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter from which packages should be uninstalled.
By default, uninstallation requires a virtual environment. A path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--requirements
,-r
requirementsUninstall all packages listed in the given requirements files
--system
Use the system Python to uninstall packages.
By default, uv uninstalls from 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 systemPATH
.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.May also be set with the
UV_SYSTEM_PYTHON
environment variable.--target
targetUninstall packages from the specified
--target
directory--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv pip freeze
List, in requirements format, packages installed in an environment
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--exclude-editable
Exclude any editable packages from output
--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter for which packages should be listed.
By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--strict
Validate the Python environment, to detect packages with missing dependencies and other issues
--system
List packages in the system Python environment.
Disables discovery of virtual environments.
See uv python for details on Python discovery.
May also be set with the
UV_SYSTEM_PYTHON
environment variable.--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv pip list
List, in tabular format, packages installed in an environment
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--editable
,-e
Only include editable projects
--exclude
excludeExclude the specified package(s) from the output
--exclude-editable
Exclude any editable packages from output
--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--format
formatSelect the output format between:
columns
(default),freeze
, orjson
[default: columns]
Possible values:
columns
: Display the list of packages in a human-readable tablefreeze
: Display the list of packages in apip freeze
-like format, with one package per line alongside its versionjson
: Display the list of packages in a machine-readable JSON format
--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--outdated
List outdated packages.
The latest version of each package will be shown alongside the installed version. Up-to-date packages will be omitted from the output.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter for which packages should be listed.
By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--strict
Validate the Python environment, to detect packages with missing dependencies and other issues
--system
List packages in the system Python environment.
Disables discovery of virtual environments.
See uv python for details on Python discovery.
May also be set with the
UV_SYSTEM_PYTHON
environment variable.--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv pip show
Show information about one or more installed packages
Usage
Arguments
PACKAGE
The package(s) to display
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--files
,-f
Show the full list of installed files for each package
--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter to find the package in.
By default, uv looks for packages in a virtual environment but will look for packages in a system Python environment if no virtual environment is found.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--strict
Validate the Python environment, to detect packages with missing dependencies and other issues
--system
Show a package in the system Python environment.
Disables discovery of virtual environments.
See uv python for details on Python discovery.
May also be set with the
UV_SYSTEM_PYTHON
environment variable.--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv pip tree
Display the dependency tree for an environment
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--depth
,-d
depthMaximum display depth of the dependency tree
[default: 255]
--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--invert
Show the reverse dependencies for the given package. This flag will invert the tree and display the packages that depend on the given package
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-dedupe
Do not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its dependencies, and will include a (*) to indicate it has already been shown. This flag will cause those duplicates to be repeated
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--outdated
Show the latest available version of each package in the tree
--package
packageDisplay only the specified packages
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--prune
prunePrune the given package from the display of the dependency tree
--python
,-p
pythonThe Python interpreter for which packages should be listed.
By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--show-version-specifiers
Show the version constraint(s) imposed on each package
--strict
Validate the Python environment, to detect packages with missing dependencies and other issues
--system
List packages in the system Python environment.
Disables discovery of virtual environments.
See uv python for details on Python discovery.
May also be set with the
UV_SYSTEM_PYTHON
environment variable.--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv pip check
Verify installed packages have compatible dependencies
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter for which packages should be checked.
By default, uv checks packages in a virtual environment but will check packages in a system Python environment if no virtual environment is found.
See uv python for details on Python discovery and supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--system
Check packages in the system Python environment.
Disables discovery of virtual environments.
See uv python for details on Python discovery.
May also be set with the
UV_SYSTEM_PYTHON
environment variable.--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv venv
Create a virtual environment.
By default, creates a virtual environment named .venv
in the working directory. An alternative path may be provided positionally.
If in a project, the default environment name can be changed with the UV_PROJECT_ENVIRONMENT
environment variable; this only applies when run from the project root directory.
If a virtual environment exists at the target path, it will be removed and a new, empty virtual environment will be created.
When using uv, the virtual environment does not need to be activated. uv will find a virtual environment (named .venv
) in the working directory or any parent directories.
Usage
Arguments
PATH
The path to the virtual environment to create.
Default to
.venv
in the working directory.Relative paths are resolved relative to the working directory.
Options
--allow-existing
Preserve any existing files or directories at the target path.
By default,
uv venv
will remove an existing virtual environment at the given path, and exit with an error if the path is non-empty but not a virtual environment. The--allow-existing
option will instead write to the given path, regardless of its contents, and without clearing it beforehand.WARNING: This option can lead to unexpected behavior if the existing virtual environment and the newly-created virtual environment are linked to different Python interpreters.
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
This option is only used for installing seed packages.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-project
Avoid discovering a project or workspace.
By default, uv searches for projects in the current directory or any parent directory to determine the default path of the virtual environment and check for Python version constraints, if any.
--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--prompt
promptProvide an alternative prompt prefix for the virtual environment.
By default, the prompt is dependent on whether a path was provided to
uv venv
. If provided (e.g,uv venv project
), the prompt is set to the directory name. If not provided (uv venv
), the prompt is set to the current directory’s name.If "." is provided, the the current directory name will be used regardless of whether a path was provided to
uv venv
.--python
,-p
pythonThe Python interpreter to use for the virtual environment.
During virtual environment creation, uv will not look for Python interpreters in virtual environments.
See
uv python help
for details on Python discovery and supported request formats.May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--relocatable
Make the virtual environment relocatable.
A relocatable virtual environment can be moved around and redistributed without invalidating its associated entrypoint and activation scripts.
Note that this can only be guaranteed for standard
console_scripts
andgui_scripts
. Other scripts may be adjusted if they ship with a generic#!python[w]
shebang, and binaries are left as-is.As a result of making the environment relocatable (by way of writing relative, rather than absolute paths), the entrypoints and scripts themselves will not be relocatable. In other words, copying those entrypoints and scripts to a location outside the environment will not work, as they reference paths relative to the environment itself.
--seed
Install seed packages (one or more of:
pip
,setuptools
, andwheel
) into the virtual environment.Note
setuptools
andwheel
are not included in Python 3.12+ environments.--system-site-packages
Give the virtual environment access to the system site packages directory.
Unlike
pip
, when a virtual environment is created with--system-site-packages
, uv will not take system site packages into account when running commands likeuv pip list
oruv pip install
. The--system-site-packages
flag will provide the virtual environment with access to the system site packages directory at runtime, but will not affect the behavior of uv commands.--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv build
Build Python packages into source distributions and wheels.
uv build
accepts a path to a directory or source distribution, which defaults to the current working directory.
By default, if passed a directory, uv build
will build a source distribution ("sdist") from the source directory, and a binary distribution ("wheel") from the source distribution.
uv build --sdist
can be used to build only the source distribution, uv build --wheel
can be used to build only the binary distribution, and uv build --sdist --wheel
can be used to build both distributions from source.
If passed a source distribution, uv build --wheel
will build a wheel from the source distribution.
Usage
Arguments
SRC
The directory from which distributions should be built, or a source distribution archive to build into a wheel.
Defaults to the current working directory.
Options
--all-packages
Builds all packages in the workspace.
The workspace will be discovered from the provided source directory, or the current directory if no source directory is provided.
If the workspace member does not exist, uv will exit with an error.
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--build-constraints
,-b
build-constraintsConstrain build dependencies using the given requirements files when building distributions.
Constraints files are
requirements.txt
-like files that only control the version of a build dependency that’s installed. However, including a package in a constraints file will not trigger the inclusion of that package on its own.May also be set with the
UV_BUILD_CONSTRAINT
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--config-setting
,-C
config-settingSettings to pass to the PEP 517 build backend, specified as
KEY=VALUE
pairs--default-index
default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the
--index
flag.May also be set with the
UV_DEFAULT_INDEX
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--exclude-newer
exclude-newerLimit 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.May also be set with the
UV_EXCLUDE_NEWER
environment variable.--extra-index-url
extra-index-url(Deprecated: use
--index
instead) 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
(which defaults to PyPI). When multiple--extra-index-url
flags are provided, earlier values take priority.May also be set with the
UV_EXTRA_INDEX_URL
environment variable.--find-links
,-f
find-linksLocations 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.
May also be set with the
UV_FIND_LINKS
environment variable.--force-pep517
Always build through PEP 517, don’t use the fast path for the uv build backend.
By default, uv won’t create a PEP 517 build environment for packages using the uv build backend, but use a fast path that calls into the build backend directly. This option forces always using PEP 517.
--help
,-h
Display the concise help for this command
--index
indexThe URLs to use when resolving dependencies, in addition to the default index.
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
--default-index
(which defaults to PyPI). When multiple--index
flags are provided, earlier values take priority.May also be set with the
UV_INDEX
environment variable.--index-strategy
index-strategyThe 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.May also be set with the
UV_INDEX_STRATEGY
environment variable.Possible values:
first-index
: Only use results from the first index that returns a match for a given package nameunsafe-first-match
: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-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
--index-url
,-i
index-url(Deprecated: use
--default-index
instead) 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 given by this flag is given lower priority than all other indexes specified via the
--extra-index-url
flag.May also be set with the
UV_INDEX_URL
environment variable.--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for index URLs.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--link-mode
link-modeThe method to use when installing packages from the global cache.
This option is only used when building source distributions.
Defaults to
clone
(also known as Copy-on-Write) on macOS, andhardlink
on Linux and Windows.May also be set with the
UV_LINK_MODE
environment variable.Possible values:
clone
: Clone (i.e., copy-on-write) packages from the wheel into thesite-packages
directorycopy
: Copy packages from the wheel into thesite-packages
directoryhardlink
: Hard link packages from the wheel into thesite-packages
directorysymlink
: Symbolically link packages from the wheel into thesite-packages
directory
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--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.
--no-binary-package
no-binary-packageDon’t install pre-built wheels for a specific package
--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.
--no-build-isolation
Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the
UV_NO_BUILD_ISOLATION
environment variable.--no-build-isolation-package
no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages’ build dependencies specified by PEP 518 are already installed.
--no-build-logs
Hide logs from the build backend
--no-build-package
no-build-packageDon’t build source distributions for a specific package
--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-index
Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via
--find-links
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--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--no-verify-hashes
Disable validation of hashes in the requirements file.
By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use
--require-hashes
.May also be set with the
UV_NO_VERIFY_HASHES
environment variable.--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--out-dir
,-o
out-dirThe output directory to which distributions should be written.
Defaults to the
dist
subdirectory within the source directory, or the directory containing the source distribution archive.--package
packageBuild a specific package in the workspace.
The workspace will be discovered from the provided source directory, or the current directory if no source directory is provided.
If the workspace member does not exist, uv will exit with an error.
--prerelease
prereleaseThe 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
).May also be set with the
UV_PRERELEASE
environment variable.Possible values:
disallow
: Disallow all pre-release versionsallow
: Allow all pre-release versionsif-necessary
: Allow pre-release versions if all versions of a package are pre-releaseexplicit
: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-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
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python
,-p
pythonThe Python interpreter to use for the build environment.
By default, builds are executed in isolated virtual environments. The discovered interpreter will be used to create those environments, and will be symlinked or copied in depending on the platform.
See uv python to view supported request formats.
May also be set with the
UV_PYTHON
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--refresh
Refresh all cached data
--refresh-package
refresh-packageRefresh cached data for a specific package
--require-hashes
Require a matching hash for each requirement.
By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash.
When
--require-hashes
is enabled, all requirements must include a hash or set of hashes, and 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.
May also be set with the
UV_REQUIRE_HASHES
environment variable.- Git dependencies are not supported. - Editable installs are not supported. - Local dependencies are not supported, unless they point to a specific wheel (
--resolution
resolutionThe 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
).May also be set with the
UV_RESOLUTION
environment variable.Possible values:
highest
: Resolve the highest compatible version of each packagelowest
: Resolve the lowest compatible version of each packagelowest-direct
: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--sdist
Build a source distribution ("sdist") from the given directory
--upgrade
,-U
Allow package upgrades, ignoring pinned versions in any existing output file. Implies
--refresh
--upgrade-package
,-P
upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies
--refresh-package
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
--wheel
Build a binary distribution ("wheel") from the given directory
uv publish
Upload distributions to an index
Usage
Arguments
FILES
Paths to the files to upload. Accepts glob expressions.
Defaults to the
dist
directory. Selects only wheels and source distributions, while ignoring other files.
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--check-url
check-urlCheck an index URL for existing files to skip duplicate uploads.
This option allows retrying publishing that failed after only some, but not all files have been uploaded, and handles error due to parallel uploads of the same file.
Before uploading, the index is checked. If the exact same file already exists in the index, the file will not be uploaded. If an error occurred during the upload, the index is checked again, to handle cases where the identical file was uploaded twice in parallel.
The exact behavior will vary based on the index. When uploading to PyPI, uploading the same file succeeds even without
--check-url
, while most other indexes error.The index must provide one of the supported hashes (SHA-256, SHA-384, or SHA-512).
May also be set with the
UV_PUBLISH_CHECK_URL
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--keyring-provider
keyring-providerAttempt to use
keyring
for authentication for remote requirements files.At present, only
--keyring-provider subprocess
is supported, which configures uv to use thekeyring
CLI to handle authentication.Defaults to
disabled
.May also be set with the
UV_KEYRING_PROVIDER
environment variable.Possible values:
disabled
: Do not use keyring for credential lookupsubprocess
: Use thekeyring
command for credential lookup
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--password
,-p
passwordThe password for the upload
May also be set with the
UV_PUBLISH_PASSWORD
environment variable.--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--publish-url
publish-urlThe URL of the upload endpoint (not the index URL).
Note that there are typically different URLs for index access (e.g.,
https:://.../simple
) and index upload.Defaults to PyPI’s publish URL (<https://upload.pypi.org/legacy/>).
May also be set with the
UV_PUBLISH_URL
environment variable.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--token
,-t
tokenThe token for the upload.
Using a token is equivalent to passing
__token__
as--username
and the token as--password
password.May also be set with the
UV_PUBLISH_TOKEN
environment variable.--trusted-publishing
trusted-publishingConfigure using trusted publishing through 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).
Possible values:
automatic
: Try trusted publishing when we’re already in GitHub Actions, continue if that failsalways
never
--username
,-u
usernameThe username for the upload
May also be set with the
UV_PUBLISH_USERNAME
environment variable.--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv cache
Manage uv's cache
Usage
Commands
uv cache clean
Clear the cache, removing all entries or those linked to specific packages
uv cache prune
Prune all unreachable objects from the cache
uv cache dir
Show the cache directory
uv cache clean
Clear the cache, removing all entries or those linked to specific packages
Usage
Arguments
PACKAGE
The packages to remove from the cache
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv cache prune
Prune all unreachable objects from the cache
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--ci
Optimize the cache for persistence in a continuous integration environment, like GitHub Actions.
By default, uv caches both the wheels that it builds from source and the pre-built wheels that it downloads directly, to enable high-performance package installation. In some scenarios, though, persisting pre-built wheels may be undesirable. For example, in GitHub Actions, it’s faster to omit pre-built wheels from the cache and instead have re-download them on each run. However, it typically is faster to cache wheels that are built from source, since the wheel building process can be expensive, especially for extension modules.
In
--ci
mode, uv will prune any pre-built wheels from the cache, but retain any wheels that were built from source.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv cache dir
Show the cache directory.
By default, the cache is stored in $XDG_CACHE_HOME/uv
or $HOME/.cache/uv
on Unix and %LOCALAPPDATA%\uv\cache
on Windows.
When --no-cache
is used, the cache is stored in a temporary directory and discarded when the process exits.
An alternative cache directory may be specified via the cache-dir
setting, the --cache-dir
option, or the $UV_CACHE_DIR
environment variable.
Note that it is important for performance for the cache directory to be located on the same file system as the Python environment uv is operating on.
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv self
Manage the uv executable
Usage
Commands
uv self update
Update uv
uv self update
Update uv
Usage
Arguments
TARGET_VERSION
Update to the specified version. If not provided, uv will update to the latest version
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--token
tokenA GitHub token for authentication. A token is not required but can be used to reduce the chance of encountering rate limits
May also be set with the
UV_GITHUB_TOKEN
environment variable.--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv version
Display uv's version
Usage
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--output-format
output-format--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version
uv generate-shell-completion
Generate shell completion
Usage
Arguments
SHELL
The shell to generate the completion script for
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.
uv help
Display documentation for a command
Usage
Arguments
COMMAND
Options
--allow-insecure-host
allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
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.May also be set with the
UV_INSECURE_HOST
environment variable.--cache-dir
cache-dirPath to the cache directory.
Defaults to
$XDG_CACHE_HOME/uv
or$HOME/.cache/uv
on macOS and Linux, and%LOCALAPPDATA%\uv\cache
on Windows.To view the location of the cache directory, run
uv cache dir
.May also be set with the
UV_CACHE_DIR
environment variable.--color
color-choiceControl colors in output
[default: auto]
Possible values:
auto
: Enables colored output only when the output is going to a terminal or TTY with supportalways
: Enables colored output regardless of the detected environmentnever
: Disables colored output
--config-file
config-fileThe path to a
uv.toml
file to use for configuration.While uv configuration can be included in a
pyproject.toml
file, it is not allowed in this context.May also be set with the
UV_CONFIG_FILE
environment variable.--directory
directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See
--project
to only change the project root directory.--help
,-h
Display the concise help for this command
--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. Thewebpki-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.
May also be set with the
UV_NATIVE_TLS
environment variable.--no-cache
,-n
Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the
UV_NO_CACHE
environment variable.--no-config
Avoid discovering configuration files (
pyproject.toml
,uv.toml
).Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the
UV_NO_CONFIG
environment variable.--no-pager
Disable pager when printing help
--no-progress
Hide all progress outputs.
For example, spinners or progress bars.
May also be set with the
UV_NO_PROGRESS
environment variable.--no-python-downloads
Disable automatic downloads of Python.
--offline
Disable network access.
When disabled, uv will only use locally cached data and locally available files.
--project
projectRun the command within the given project directory.
All
pyproject.toml
,uv.toml
, and.python-version
files will be discovered by walking up the directory tree from the project root, as will the project’s virtual environment (.venv
).Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See
--directory
to change the working directory entirely.This setting has no effect when used in the
uv pip
interface.--python-preference
python-preferenceWhether to prefer uv-managed or system Python installations.
By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.
May also be set with the
UV_PYTHON_PREFERENCE
environment variable.Possible values:
only-managed
: Only use managed Python installations; never use system Python installationsmanaged
: Prefer managed Python installations over system Python installationssystem
: Prefer system Python installations over managed Python installationsonly-system
: Only use system Python installations; never use managed Python installations
--quiet
,-q
Do not print any output
--verbose
,-v
Use verbose output.
You can configure fine-grained logging using the
RUST_LOG
environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)--version
,-V
Display the uv version