From c0c26cc5429437f03dda02415aa57bd9f3bdb1dc Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Tue, 6 Aug 2024 16:18:05 -0500 Subject: [PATCH] Improve display order of top-level commands (#5830) Closes https://github.com/astral-sh/uv/issues/5702 Since Clap 4, the default order follows the declarations. Also improves some descriptions. --- crates/uv-cli/src/lib.rs | 56 +- crates/uv/tests/help.rs | 114 +- docs/reference/cli.md | 4420 +++++++++++++++++++------------------- 3 files changed, 2295 insertions(+), 2295 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 98311fe6e..69dbc66f3 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -213,12 +213,9 @@ impl From for anstream::ColorChoice { #[derive(Subcommand)] #[allow(clippy::large_enum_variant)] pub enum Commands { - /// Manage Python packages with a pip-compatible interface. - #[command( - after_help = "Use `uv help pip`` for more details.", - after_long_help = "" - )] - Pip(PipNamespace), + /// Manage Python projects. + #[command(flatten)] + Project(Box), /// Run and manage tools provided by Python packages (experimental). #[command( after_help = "Use `uv help tool` for more details.", @@ -231,9 +228,12 @@ pub enum Commands { after_long_help = "" )] Python(PythonNamespace), - /// Manage Python projects. - #[command(flatten)] - Project(Box), + /// Manage Python packages with a pip-compatible interface. + #[command( + after_help = "Use `uv help pip`` for more details.", + after_long_help = "" + )] + Pip(PipNamespace), /// Create a virtual environment. #[command( alias = "virtualenv", @@ -242,7 +242,7 @@ pub enum Commands { after_long_help = "" )] Venv(VenvArgs), - /// Manage the cache. + /// Manage uv's cache. #[command( after_help = "Use `uv help cache` for more details.", after_long_help = "" @@ -415,39 +415,39 @@ pub enum PipCommand { #[derive(Subcommand)] pub enum ProjectCommand { - /// Create a new project (experimental). - Init(InitArgs), - /// Run a command in an environment (experimental). + /// Run a command or script (experimental). #[command( after_help = "Use `uv help run` for more details.", after_long_help = "" )] Run(RunArgs), - /// Update the project's environment to match the project's dependencies (experimental). - #[command( - after_help = "Use `uv help sync` for more details.", - after_long_help = "" - )] - Sync(SyncArgs), - /// Create or update a lockfile for the project's dependencies (experimental). - #[command( - after_help = "Use `uv help lock` for more details.", - after_long_help = "" - )] - Lock(LockArgs), - /// Add one or more packages to the project's dependencies (experimental). + /// Create a new project (experimental). + Init(InitArgs), + /// Add dependencies to the project (experimental). #[command( after_help = "Use `uv help add` for more details.", after_long_help = "" )] Add(AddArgs), - /// Remove one or more packages from the project's dependencies (experimental). + /// Remove dependencies from the project (experimental). #[command( after_help = "Use `uv help remove` for more details.", after_long_help = "" )] Remove(RemoveArgs), - /// Display the dependency tree for the project (experimental). + /// Update the project's environment (experimental). + #[command( + after_help = "Use `uv help sync` for more details.", + after_long_help = "" + )] + Sync(SyncArgs), + /// Update the project's lockfile (experimental). + #[command( + after_help = "Use `uv help lock` for more details.", + after_long_help = "" + )] + Lock(LockArgs), + /// Display the project's dependency tree (experimental). Tree(TreeArgs), } diff --git a/crates/uv/tests/help.rs b/crates/uv/tests/help.rs index 7a2519973..3c511d6e5 100644 --- a/crates/uv/tests/help.rs +++ b/crates/uv/tests/help.rs @@ -16,18 +16,18 @@ fn help() { Usage: uv [OPTIONS] Commands: - pip Manage Python packages with a pip-compatible interface + run Run a command or script (experimental) + init Create a new project (experimental) + add Add dependencies to the project (experimental) + remove Remove dependencies from the project (experimental) + sync Update the project's environment (experimental) + lock Update the project's lockfile (experimental) + tree Display the project's dependency tree (experimental) tool Run and manage tools provided by Python packages (experimental) python Manage Python versions and installations (experimental) - init Create a new project (experimental) - run Run a command in an environment (experimental) - sync Update the project's environment to match the project's dependencies (experimental) - lock Create or update a lockfile for the project's dependencies (experimental) - add Add one or more packages to the project's dependencies (experimental) - remove Remove one or more packages from the project's dependencies (experimental) - tree Display the dependency tree for the project (experimental) + pip Manage Python packages with a pip-compatible interface venv Create a virtual environment - cache Manage the cache + cache Manage uv's cache version Display uv's version help Display documentation for a command @@ -82,18 +82,18 @@ fn help_flag() { Usage: uv [OPTIONS] Commands: - pip Manage Python packages with a pip-compatible interface + run Run a command or script (experimental) + init Create a new project (experimental) + add Add dependencies to the project (experimental) + remove Remove dependencies from the project (experimental) + sync Update the project's environment (experimental) + lock Update the project's lockfile (experimental) + tree Display the project's dependency tree (experimental) tool Run and manage tools provided by Python packages (experimental) python Manage Python versions and installations (experimental) - init Create a new project (experimental) - run Run a command in an environment (experimental) - sync Update the project's environment to match the project's dependencies (experimental) - lock Create or update a lockfile for the project's dependencies (experimental) - add Add one or more packages to the project's dependencies (experimental) - remove Remove one or more packages from the project's dependencies (experimental) - tree Display the dependency tree for the project (experimental) + pip Manage Python packages with a pip-compatible interface venv Create a virtual environment - cache Manage the cache + cache Manage uv's cache version Display uv's version help Display documentation for a command @@ -147,18 +147,18 @@ fn help_short_flag() { Usage: uv [OPTIONS] Commands: - pip Manage Python packages with a pip-compatible interface + run Run a command or script (experimental) + init Create a new project (experimental) + add Add dependencies to the project (experimental) + remove Remove dependencies from the project (experimental) + sync Update the project's environment (experimental) + lock Update the project's lockfile (experimental) + tree Display the project's dependency tree (experimental) tool Run and manage tools provided by Python packages (experimental) python Manage Python versions and installations (experimental) - init Create a new project (experimental) - run Run a command in an environment (experimental) - sync Update the project's environment to match the project's dependencies (experimental) - lock Create or update a lockfile for the project's dependencies (experimental) - add Add one or more packages to the project's dependencies (experimental) - remove Remove one or more packages from the project's dependencies (experimental) - tree Display the dependency tree for the project (experimental) + pip Manage Python packages with a pip-compatible interface venv Create a virtual environment - cache Manage the cache + cache Manage uv's cache version Display uv's version help Display documentation for a command @@ -565,16 +565,16 @@ fn help_unknown_subcommand() { ----- stderr ----- error: There is no command `foobar` for `uv`. Did you mean one of: - pip - tool - python - init run - sync - lock + init add remove + sync + lock tree + tool + python + pip venv cache version @@ -587,16 +587,16 @@ fn help_unknown_subcommand() { ----- stderr ----- error: There is no command `foo bar` for `uv`. Did you mean one of: - pip - tool - python - init run - sync - lock + init add remove + sync + lock tree + tool + python + pip venv cache version @@ -636,18 +636,18 @@ fn help_with_global_option() { Usage: uv [OPTIONS] Commands: - pip Manage Python packages with a pip-compatible interface + run Run a command or script (experimental) + init Create a new project (experimental) + add Add dependencies to the project (experimental) + remove Remove dependencies from the project (experimental) + sync Update the project's environment (experimental) + lock Update the project's lockfile (experimental) + tree Display the project's dependency tree (experimental) tool Run and manage tools provided by Python packages (experimental) python Manage Python versions and installations (experimental) - init Create a new project (experimental) - run Run a command in an environment (experimental) - sync Update the project's environment to match the project's dependencies (experimental) - lock Create or update a lockfile for the project's dependencies (experimental) - add Add one or more packages to the project's dependencies (experimental) - remove Remove one or more packages from the project's dependencies (experimental) - tree Display the dependency tree for the project (experimental) + pip Manage Python packages with a pip-compatible interface venv Create a virtual environment - cache Manage the cache + cache Manage uv's cache version Display uv's version help Display documentation for a command @@ -738,18 +738,18 @@ fn help_with_no_pager() { Usage: uv [OPTIONS] Commands: - pip Manage Python packages with a pip-compatible interface + run Run a command or script (experimental) + init Create a new project (experimental) + add Add dependencies to the project (experimental) + remove Remove dependencies from the project (experimental) + sync Update the project's environment (experimental) + lock Update the project's lockfile (experimental) + tree Display the project's dependency tree (experimental) tool Run and manage tools provided by Python packages (experimental) python Manage Python versions and installations (experimental) - init Create a new project (experimental) - run Run a command in an environment (experimental) - sync Update the project's environment to match the project's dependencies (experimental) - lock Create or update a lockfile for the project's dependencies (experimental) - add Add one or more packages to the project's dependencies (experimental) - remove Remove one or more packages from the project's dependencies (experimental) - tree Display the dependency tree for the project (experimental) + pip Manage Python packages with a pip-compatible interface venv Create a virtual environment - cache Manage the cache + cache Manage uv's cache version Display uv's version help Display documentation for a command diff --git a/docs/reference/cli.md b/docs/reference/cli.md index c2b5f4db8..74cac68a0 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -12,29 +12,29 @@ uv [OPTIONS]

Commands

-
uv pip

Manage Python packages with a pip-compatible interface

+
uv run

Run a command or script (experimental)

+
+
uv init

Create a new project (experimental)

+
+
uv add

Add dependencies to the project (experimental)

+
+
uv remove

Remove dependencies from the project (experimental)

+
+
uv sync

Update the project’s environment (experimental)

+
+
uv lock

Update the project’s lockfile (experimental)

+
+
uv tree

Display the project’s dependency tree (experimental)

uv tool

Run and manage tools provided by Python packages (experimental)

uv python

Manage Python versions and installations (experimental)

-
uv init

Create a new project (experimental)

-
-
uv run

Run a command in an environment (experimental)

-
-
uv sync

Update the project’s environment to match the project’s dependencies (experimental)

-
-
uv lock

Create or update a lockfile for the project’s dependencies (experimental)

-
-
uv add

Add one or more packages to the project’s dependencies (experimental)

-
-
uv remove

Remove one or more packages from the project’s dependencies (experimental)

-
-
uv tree

Display the dependency tree for the project (experimental)

+
uv pip

Manage Python packages with a pip-compatible interface

uv venv

Create a virtual environment

-
uv cache

Manage the cache

+
uv cache

Manage uv’s cache

uv version

Display uv’s version

@@ -42,6 +42,2200 @@ uv [OPTIONS]
+## uv run + +Run a command or script (experimental) + +

Usage

+ +``` +uv run [OPTIONS] +``` + +

Options

+ +
--extra extra

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

+ +

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

+ +
--with with

Run with the given packages installed

+ +
--with-requirements with-requirements

Run with all packages listed in the given requirements.txt files.

+ +

Using pyproject.toml, setup.py, or setup.cfg files is not allowed.

+ +
--index-url, -i index-url

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

+ +

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

+ +

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

+ +

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

+ +

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

+ +
--find-links, -f find-links

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

+ +

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

+ +
--upgrade-package, -P upgrade-package

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

+ +
--reinstall-package reinstall-package

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

+ +
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

+ +

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

+ +

Possible values:

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

Attempt to use keyring for authentication for index URLs.

+ +

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

+ +

Defaults to disabled.

+ +

Possible values:

+ +
    +
  • disabled: Do not use keyring for credential lookup
    • + +
  • subprocess: Use the keyring command for credential lookup
    • +
+
--resolution resolution

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

+ +

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

+ +

Possible values:

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

The strategy to use when considering pre-release versions.

+ +

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

+ +

Possible values:

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

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

+ +
--exclude-newer exclude-newer

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

+ +

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

+ +
--link-mode link-mode

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

+ +

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

+ +

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

+ +
--refresh-package refresh-package

Refresh cached data for a specific package

+ +
--package package

Run the command in a specific package in the workspace

+ +
--python, -p python

The Python interpreter to use to build the run 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 --python option allows you to specify a different interpreter.

+ +

Supported formats:

+ +
    +
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • + +
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • + +
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • +
+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +## uv init + +Create a new project (experimental) + +

Usage

+ +``` +uv init [OPTIONS] [PATH] +``` + +

Arguments

+ +
PATH

The path of the project

+ +
+ +

Options

+ +
--name name

The name of the project, defaults to the name of the directory

+ +
--python, -p python

The Python interpreter to use to determine the minimum supported Python version.

+ +

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 --python option allows you to specify a different interpreter.

+ +

Supported formats:

+ +
    +
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • + +
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • + +
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • +
+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +## uv add + +Add dependencies to the project (experimental) + +

Usage

+ +``` +uv add [OPTIONS] ... +``` + +

Arguments

+ +
REQUIREMENTS

The packages to add, as PEP 508 requirements (e.g., ruff==0.5.0)

+ +
+ +

Options

+ +
--optional optional

Add the requirements to the specified optional dependency group

+ +
--rev rev

Specific commit to use when adding from Git

+ +
--tag tag

Tag to use when adding from git

+ +
--branch branch

Branch to use when adding from git

+ +
--extra extra

Extras to activate for the dependency; may be provided more than once

+ +
--index-url, -i index-url

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

+ +

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

+ +

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

+ +

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

+ +

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

+ +
--find-links, -f find-links

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

+ +

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

+ +
--upgrade-package, -P upgrade-package

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

+ +
--reinstall-package reinstall-package

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

+ +
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

+ +

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

+ +

Possible values:

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

Attempt to use keyring for authentication for index URLs.

+ +

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

+ +

Defaults to disabled.

+ +

Possible values:

+ +
    +
  • disabled: Do not use keyring for credential lookup
    • + +
  • subprocess: Use the keyring command for credential lookup
    • +
+
--resolution resolution

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

+ +

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

+ +

Possible values:

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

The strategy to use when considering pre-release versions.

+ +

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

+ +

Possible values:

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

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

+ +
--exclude-newer exclude-newer

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

+ +

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

+ +
--link-mode link-mode

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

+ +

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

+ +

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

+ +
--refresh-package refresh-package

Refresh cached data for a specific package

+ +
--package package

Add the dependency to a specific package in the workspace

+ +
--python, -p python

The Python interpreter into which packages should be installed.

+ +

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

+ +

Supported formats:

+ +
    +
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • + +
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • + +
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • +
+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +## uv remove + +Remove dependencies from the project (experimental) + +

Usage

+ +``` +uv remove [OPTIONS] ... +``` + +

Arguments

+ +
REQUIREMENTS

The names of the packages to remove (e.g., ruff)

+ +
+ +

Options

+ +
--optional optional

Remove the requirements from the specified optional dependency group

+ +
--index-url, -i index-url

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

+ +

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

+ +

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

+ +

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

+ +

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

+ +
--find-links, -f find-links

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

+ +

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

+ +
--upgrade-package, -P upgrade-package

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

+ +
--reinstall-package reinstall-package

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

+ +
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

+ +

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

+ +

Possible values:

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

Attempt to use keyring for authentication for index URLs.

+ +

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

+ +

Defaults to disabled.

+ +

Possible values:

+ +
    +
  • disabled: Do not use keyring for credential lookup
    • + +
  • subprocess: Use the keyring command for credential lookup
    • +
+
--resolution resolution

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

+ +

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

+ +

Possible values:

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

The strategy to use when considering pre-release versions.

+ +

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

+ +

Possible values:

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

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

+ +
--exclude-newer exclude-newer

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

+ +

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

+ +
--link-mode link-mode

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

+ +

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

+ +

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

+ +
--refresh-package refresh-package

Refresh cached data for a specific package

+ +
--package package

Remove the dependency from a specific package in the workspace

+ +
--python, -p python

The Python interpreter into which packages should be installed.

+ +

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

+ +

Supported formats:

+ +
    +
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • + +
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • + +
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • +
+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +## uv sync + +Update the project's environment (experimental) + +

Usage

+ +``` +uv sync [OPTIONS] +``` + +

Options

+ +
--extra extra

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

+ +

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

+ +
--index-url, -i index-url

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

+ +

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

+ +

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

+ +

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

+ +

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

+ +
--find-links, -f find-links

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

+ +

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

+ +
--upgrade-package, -P upgrade-package

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

+ +
--reinstall-package reinstall-package

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

+ +
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

+ +

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

+ +

Possible values:

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

Attempt to use keyring for authentication for index URLs.

+ +

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

+ +

Defaults to disabled.

+ +

Possible values:

+ +
    +
  • disabled: Do not use keyring for credential lookup
    • + +
  • subprocess: Use the keyring command for credential lookup
    • +
+
--resolution resolution

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

+ +

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

+ +

Possible values:

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

The strategy to use when considering pre-release versions.

+ +

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

+ +

Possible values:

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

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

+ +
--exclude-newer exclude-newer

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

+ +

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

+ +
--link-mode link-mode

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

+ +

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

+ +

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

+ +
--refresh-package refresh-package

Refresh cached data for a specific package

+ +
--package package

Sync a specific package in the workspace

+ +
--python, -p python

The Python interpreter to use to build the run 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 --python option allows you to specify a different interpreter.

+ +

Supported formats:

+ +
    +
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • + +
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • + +
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • +
+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +## uv lock + +Update the project's lockfile (experimental) + +

Usage

+ +``` +uv lock [OPTIONS] +``` + +

Options

+ +
--index-url, -i index-url

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

+ +

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

+ +

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

+ +

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

+ +

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

+ +
--find-links, -f find-links

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

+ +

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

+ +
--upgrade-package, -P upgrade-package

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

+ +
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

+ +

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

+ +

Possible values:

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

Attempt to use keyring for authentication for index URLs.

+ +

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

+ +

Defaults to disabled.

+ +

Possible values:

+ +
    +
  • disabled: Do not use keyring for credential lookup
    • + +
  • subprocess: Use the keyring command for credential lookup
    • +
+
--resolution resolution

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

+ +

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

+ +

Possible values:

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

The strategy to use when considering pre-release versions.

+ +

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

+ +

Possible values:

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

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

+ +
--exclude-newer exclude-newer

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

+ +

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

+ +
--link-mode link-mode

The 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, and hardlink on Linux and Windows.

+ +

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

+ +
--refresh-package refresh-package

Refresh cached data for a specific package

+ +
--python, -p python

The Python interpreter to use to build the run 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 --python option allows you to specify a different interpreter.

+ +

Supported formats:

+ +
    +
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • + +
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • + +
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • +
+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +## uv tree + +Display the project's dependency tree (experimental) + +

Usage

+ +``` +uv tree [OPTIONS] +``` + +

Options

+ +
--depth, -d depth

Maximum display depth of the dependency tree

+ +

[default: 255]

+
--prune prune

Prune the given package from the display of the dependency tree

+ +
--package package

Display only the specified packages

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

+ +
--index-url, -i index-url

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

+ +

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

+ +

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

+ +

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

+ +

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

+ +
--find-links, -f find-links

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

+ +

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

+ +
--upgrade-package, -P upgrade-package

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

+ +
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

+ +

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

+ +

Possible values:

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

Attempt to use keyring for authentication for index URLs.

+ +

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

+ +

Defaults to disabled.

+ +

Possible values:

+ +
    +
  • disabled: Do not use keyring for credential lookup
    • + +
  • subprocess: Use the keyring command for credential lookup
    • +
+
--resolution resolution

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

+ +

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

+ +

Possible values:

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

The strategy to use when considering pre-release versions.

+ +

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

+ +

Possible values:

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

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

+ +
--exclude-newer exclude-newer

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

+ +

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

+ +
--link-mode link-mode

The 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, and hardlink on Linux and Windows.

+ +

Possible values:

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

The Python version to use when filtering the tree (via --filter). For example, pass --python-version 3.10 to display the dependencies that would be included when installing on Python 3.10

+ +
--python-platform python-platform

The platform to use when filtering the tree (via --filter). 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 or aaarch64-apple-darwin.

+ +

Possible values:

+ +
    +
  • windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
    • + +
  • linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
    • + +
  • macos: An alias for aarch64-apple-darwin, the default target for macOS
    • + +
  • x86_64-pc-windows-msvc: An x86 Windows target
    • + +
  • x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_17
    • + +
  • aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
    • + +
  • x86_64-apple-darwin: An x86 macOS target
    • + +
  • aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_17
    • + +
  • aarch64-unknown-linux-musl: An ARM64 Linux target
    • + +
  • x86_64-unknown-linux-musl: An x86_64 Linux target
    • + +
  • x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
    • + +
  • x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
    • + +
  • x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
    • + +
  • aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
    • + +
  • aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
    • + +
  • aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
    • +
+
--python, -p python

The Python interpreter for which packages should be listed.

+ +

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

+ +

Supported formats:

+ +
    +
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • + +
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • + +
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • +
+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +## uv tool + +Run and manage tools provided by Python packages (experimental) + +

Usage

+ +``` +uv tool [OPTIONS] +``` + +

Commands

+ +
uv tool run

Run a tool

+
+
uv tool install

Install a tool

+
+
uv tool list

List installed tools

+
+
uv tool uninstall

Uninstall a tool

+
+
uv tool update-shell

Ensure that the tool executable directory is on PATH

+
+
uv tool dir

Show the tools directory

+
+
+ +### uv tool run + +Run a tool + +

Usage

+ +``` +uv tool run [OPTIONS] [COMMAND] +``` + +

Options

+ +
--from from

Use the given package to provide the command.

+ +

By default, the package name is assumed to match the command name.

+ +
--with with

Run with the given packages installed

+ +
--with-requirements with-requirements

Run with all packages listed in the given requirements.txt files

+ +
--index-url, -i index-url

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

+ +

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

+ +

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

+ +

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

+ +

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

+ +
--find-links, -f find-links

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

+ +

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

+ +
--upgrade-package, -P upgrade-package

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

+ +
--reinstall-package reinstall-package

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

+ +
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

+ +

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

+ +

Possible values:

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

Attempt to use keyring for authentication for index URLs.

+ +

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

+ +

Defaults to disabled.

+ +

Possible values:

+ +
    +
  • disabled: Do not use keyring for credential lookup
    • + +
  • subprocess: Use the keyring command for credential lookup
    • +
+
--resolution resolution

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

+ +

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

+ +

Possible values:

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

The strategy to use when considering pre-release versions.

+ +

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

+ +

Possible values:

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

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

+ +
--exclude-newer exclude-newer

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

+ +

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

+ +
--link-mode link-mode

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

+ +

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

+ +

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

+ +
--refresh-package refresh-package

Refresh cached data for a specific package

+ +
--python, -p python

The Python interpreter to use to build the run 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 --python option allows you to specify a different interpreter.

+ +

Supported formats:

+ +
    +
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • + +
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • + +
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • +
+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +### uv tool install + +Install a tool + +

Usage

+ +``` +uv tool install [OPTIONS] +``` + +

Arguments

+ +
PACKAGE

The package to install commands from

+ +
+ +

Options

+ +
--with with

Include the following extra requirements

+ +
--with-requirements with-requirements

Run all requirements listed in the given requirements.txt files

+ +
--index-url, -i index-url

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

+ +

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

+ +

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

+ +

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

+ +

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

+ +
--find-links, -f find-links

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

+ +

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

+ +
--upgrade-package, -P upgrade-package

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

+ +
--reinstall-package reinstall-package

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

+ +
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

+ +

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

+ +

Possible values:

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

Attempt to use keyring for authentication for index URLs.

+ +

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

+ +

Defaults to disabled.

+ +

Possible values:

+ +
    +
  • disabled: Do not use keyring for credential lookup
    • + +
  • subprocess: Use the keyring command for credential lookup
    • +
+
--resolution resolution

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

+ +

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

+ +

Possible values:

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

The strategy to use when considering pre-release versions.

+ +

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

+ +

Possible values:

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

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

+ +
--exclude-newer exclude-newer

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

+ +

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

+ +
--link-mode link-mode

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

+ +

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

+ +

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

+ +
--refresh-package refresh-package

Refresh cached data for a specific package

+ +
--python, -p python

The Python interpreter to use to build the tool environment.

+ +

By default, uv will search for a Python executable in the PATH. uv ignores virtual environments while looking for interpreter for tools. The --python option allows you to specify a different interpreter.

+ +

Supported formats:

+ +
    +
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • + +
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • + +
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • +
+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +### uv tool list + +List installed tools + +

Usage

+ +``` +uv tool list [OPTIONS] +``` + +

Options

+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +### uv tool uninstall + +Uninstall a tool + +

Usage

+ +``` +uv tool uninstall [OPTIONS] +``` + +

Arguments

+ +
NAME

The name of the tool to uninstall

+ +
+ +

Options

+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +### uv tool update-shell + +Ensure that the tool executable directory is on `PATH` + +

Usage

+ +``` +uv tool update-shell [OPTIONS] +``` + +

Options

+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +### uv tool dir + +Show the tools directory + +

Usage

+ +``` +uv tool dir [OPTIONS] +``` + +

Options

+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +## uv python + +Manage Python versions and installations (experimental) + +

Usage

+ +``` +uv python [OPTIONS] +``` + +

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 + +

Usage

+ +``` +uv python list [OPTIONS] +``` + +

Options

+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +### uv python install + +Download and install Python versions + +

Usage

+ +``` +uv python install [OPTIONS] [TARGETS]... +``` + +

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.

+ +
+ +

Options

+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +### uv python find + +Search for a Python installation + +

Usage

+ +``` +uv python find [OPTIONS] [REQUEST] +``` + +

Arguments

+ +
REQUEST

The Python request

+ +
+ +

Options

+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +### uv python pin + +Pin to a specific Python version + +

Usage

+ +``` +uv python pin [OPTIONS] [REQUEST] +``` + +

Arguments

+ +
REQUEST

The Python version

+ +
+ +

Options

+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +### uv python dir + +Show the uv Python installation directory + +

Usage

+ +``` +uv python dir [OPTIONS] +``` + +

Options

+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ +### uv python uninstall + +Uninstall Python versions + +

Usage

+ +``` +uv python uninstall [OPTIONS] ... +``` + +

Arguments

+ +
TARGETS

The Python version(s) to uninstall

+ +
+ +

Options

+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

+ +
--python-preference python-preference

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

+ +

Possible values:

+ +
    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • + +
  • managed: Prefer managed Python installations over system Python installations
    • + +
  • system: Prefer system Python installations over managed Python installations
    • + +
  • only-system: Only use system Python installations; never use managed Python installations
    • +
+
--python-fetch python-fetch

Whether to automatically download Python when required

+ +

Possible values:

+ +
    +
  • automatic: Automatically fetch managed Python installations when needed
    • + +
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • +
+
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

+ +
    +
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • + +
  • always: Enables colored output regardless of the detected environment
    • + +
  • never: Disables colored output
    • +
+
--config-file config-file

The path to a uv.toml file to use for configuration

+ +
+ ## uv pip Manage Python packages with a pip-compatible interface @@ -1295,2200 +3489,6 @@ uv pip check [OPTIONS] -## uv tool - -Run and manage tools provided by Python packages (experimental) - -

Usage

- -``` -uv tool [OPTIONS] -``` - -

Commands

- -
uv tool run

Run a tool

-
-
uv tool install

Install a tool

-
-
uv tool list

List installed tools

-
-
uv tool uninstall

Uninstall a tool

-
-
uv tool update-shell

Ensure that the tool executable directory is on PATH

-
-
uv tool dir

Show the tools directory

-
-
- -### uv tool run - -Run a tool - -

Usage

- -``` -uv tool run [OPTIONS] [COMMAND] -``` - -

Options

- -
--from from

Use the given package to provide the command.

- -

By default, the package name is assumed to match the command name.

- -
--with with

Run with the given packages installed

- -
--with-requirements with-requirements

Run with all packages listed in the given requirements.txt files

- -
--index-url, -i index-url

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

- -

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

- -

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

- -

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

- -

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

- -
--find-links, -f find-links

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

- -

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

- -
--upgrade-package, -P upgrade-package

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

- -
--reinstall-package reinstall-package

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

- -
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

- -

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

- -

Possible values:

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

Attempt to use keyring for authentication for index URLs.

- -

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

- -

Defaults to disabled.

- -

Possible values:

- -
    -
  • disabled: Do not use keyring for credential lookup
    • - -
  • subprocess: Use the keyring command for credential lookup
    • -
-
--resolution resolution

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

- -

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

- -

Possible values:

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

The strategy to use when considering pre-release versions.

- -

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

- -

Possible values:

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

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

- -
--exclude-newer exclude-newer

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

- -

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

- -
--link-mode link-mode

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

- -

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

- -

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

- -
--refresh-package refresh-package

Refresh cached data for a specific package

- -
--python, -p python

The Python interpreter to use to build the run 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 --python option allows you to specify a different interpreter.

- -

Supported formats:

- -
    -
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • - -
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • - -
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • -
- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -### uv tool install - -Install a tool - -

Usage

- -``` -uv tool install [OPTIONS] -``` - -

Arguments

- -
PACKAGE

The package to install commands from

- -
- -

Options

- -
--with with

Include the following extra requirements

- -
--with-requirements with-requirements

Run all requirements listed in the given requirements.txt files

- -
--index-url, -i index-url

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

- -

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

- -

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

- -

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

- -

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

- -
--find-links, -f find-links

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

- -

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

- -
--upgrade-package, -P upgrade-package

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

- -
--reinstall-package reinstall-package

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

- -
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

- -

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

- -

Possible values:

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

Attempt to use keyring for authentication for index URLs.

- -

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

- -

Defaults to disabled.

- -

Possible values:

- -
    -
  • disabled: Do not use keyring for credential lookup
    • - -
  • subprocess: Use the keyring command for credential lookup
    • -
-
--resolution resolution

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

- -

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

- -

Possible values:

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

The strategy to use when considering pre-release versions.

- -

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

- -

Possible values:

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

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

- -
--exclude-newer exclude-newer

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

- -

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

- -
--link-mode link-mode

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

- -

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

- -

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

- -
--refresh-package refresh-package

Refresh cached data for a specific package

- -
--python, -p python

The Python interpreter to use to build the tool environment.

- -

By default, uv will search for a Python executable in the PATH. uv ignores virtual environments while looking for interpreter for tools. The --python option allows you to specify a different interpreter.

- -

Supported formats:

- -
    -
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • - -
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • - -
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • -
- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -### uv tool list - -List installed tools - -

Usage

- -``` -uv tool list [OPTIONS] -``` - -

Options

- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -### uv tool uninstall - -Uninstall a tool - -

Usage

- -``` -uv tool uninstall [OPTIONS] -``` - -

Arguments

- -
NAME

The name of the tool to uninstall

- -
- -

Options

- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -### uv tool update-shell - -Ensure that the tool executable directory is on `PATH` - -

Usage

- -``` -uv tool update-shell [OPTIONS] -``` - -

Options

- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -### uv tool dir - -Show the tools directory - -

Usage

- -``` -uv tool dir [OPTIONS] -``` - -

Options

- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -## uv python - -Manage Python versions and installations (experimental) - -

Usage

- -``` -uv python [OPTIONS] -``` - -

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 - -

Usage

- -``` -uv python list [OPTIONS] -``` - -

Options

- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -### uv python install - -Download and install Python versions - -

Usage

- -``` -uv python install [OPTIONS] [TARGETS]... -``` - -

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.

- -
- -

Options

- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -### uv python find - -Search for a Python installation - -

Usage

- -``` -uv python find [OPTIONS] [REQUEST] -``` - -

Arguments

- -
REQUEST

The Python request

- -
- -

Options

- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -### uv python pin - -Pin to a specific Python version - -

Usage

- -``` -uv python pin [OPTIONS] [REQUEST] -``` - -

Arguments

- -
REQUEST

The Python version

- -
- -

Options

- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -### uv python dir - -Show the uv Python installation directory - -

Usage

- -``` -uv python dir [OPTIONS] -``` - -

Options

- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -### uv python uninstall - -Uninstall Python versions - -

Usage

- -``` -uv python uninstall [OPTIONS] ... -``` - -

Arguments

- -
TARGETS

The Python version(s) to uninstall

- -
- -

Options

- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -## uv init - -Create a new project (experimental) - -

Usage

- -``` -uv init [OPTIONS] [PATH] -``` - -

Arguments

- -
PATH

The path of the project

- -
- -

Options

- -
--name name

The name of the project, defaults to the name of the directory

- -
--python, -p python

The Python interpreter to use to determine the minimum supported Python version.

- -

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 --python option allows you to specify a different interpreter.

- -

Supported formats:

- -
    -
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • - -
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • - -
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • -
- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -## uv run - -Run a command in an environment (experimental) - -

Usage

- -``` -uv run [OPTIONS] -``` - -

Options

- -
--extra extra

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

- -

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

- -
--with with

Run with the given packages installed

- -
--with-requirements with-requirements

Run with all packages listed in the given requirements.txt files.

- -

Using pyproject.toml, setup.py, or setup.cfg files is not allowed.

- -
--index-url, -i index-url

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

- -

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

- -

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

- -

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

- -

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

- -
--find-links, -f find-links

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

- -

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

- -
--upgrade-package, -P upgrade-package

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

- -
--reinstall-package reinstall-package

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

- -
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

- -

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

- -

Possible values:

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

Attempt to use keyring for authentication for index URLs.

- -

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

- -

Defaults to disabled.

- -

Possible values:

- -
    -
  • disabled: Do not use keyring for credential lookup
    • - -
  • subprocess: Use the keyring command for credential lookup
    • -
-
--resolution resolution

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

- -

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

- -

Possible values:

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

The strategy to use when considering pre-release versions.

- -

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

- -

Possible values:

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

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

- -
--exclude-newer exclude-newer

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

- -

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

- -
--link-mode link-mode

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

- -

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

- -

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

- -
--refresh-package refresh-package

Refresh cached data for a specific package

- -
--package package

Run the command in a specific package in the workspace

- -
--python, -p python

The Python interpreter to use to build the run 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 --python option allows you to specify a different interpreter.

- -

Supported formats:

- -
    -
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • - -
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • - -
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • -
- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -## uv sync - -Update the project's environment to match the project's dependencies (experimental) - -

Usage

- -``` -uv sync [OPTIONS] -``` - -

Options

- -
--extra extra

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

- -

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

- -
--index-url, -i index-url

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

- -

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

- -

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

- -

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

- -

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

- -
--find-links, -f find-links

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

- -

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

- -
--upgrade-package, -P upgrade-package

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

- -
--reinstall-package reinstall-package

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

- -
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

- -

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

- -

Possible values:

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

Attempt to use keyring for authentication for index URLs.

- -

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

- -

Defaults to disabled.

- -

Possible values:

- -
    -
  • disabled: Do not use keyring for credential lookup
    • - -
  • subprocess: Use the keyring command for credential lookup
    • -
-
--resolution resolution

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

- -

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

- -

Possible values:

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

The strategy to use when considering pre-release versions.

- -

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

- -

Possible values:

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

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

- -
--exclude-newer exclude-newer

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

- -

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

- -
--link-mode link-mode

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

- -

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

- -

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

- -
--refresh-package refresh-package

Refresh cached data for a specific package

- -
--package package

Sync a specific package in the workspace

- -
--python, -p python

The Python interpreter to use to build the run 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 --python option allows you to specify a different interpreter.

- -

Supported formats:

- -
    -
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • - -
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • - -
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • -
- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -## uv lock - -Create or update a lockfile for the project's dependencies (experimental) - -

Usage

- -``` -uv lock [OPTIONS] -``` - -

Options

- -
--index-url, -i index-url

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

- -

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

- -

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

- -

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

- -

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

- -
--find-links, -f find-links

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

- -

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

- -
--upgrade-package, -P upgrade-package

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

- -
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

- -

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

- -

Possible values:

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

Attempt to use keyring for authentication for index URLs.

- -

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

- -

Defaults to disabled.

- -

Possible values:

- -
    -
  • disabled: Do not use keyring for credential lookup
    • - -
  • subprocess: Use the keyring command for credential lookup
    • -
-
--resolution resolution

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

- -

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

- -

Possible values:

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

The strategy to use when considering pre-release versions.

- -

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

- -

Possible values:

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

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

- -
--exclude-newer exclude-newer

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

- -

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

- -
--link-mode link-mode

The 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, and hardlink on Linux and Windows.

- -

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

- -
--refresh-package refresh-package

Refresh cached data for a specific package

- -
--python, -p python

The Python interpreter to use to build the run 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 --python option allows you to specify a different interpreter.

- -

Supported formats:

- -
    -
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • - -
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • - -
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • -
- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -## uv add - -Add one or more packages to the project's dependencies (experimental) - -

Usage

- -``` -uv add [OPTIONS] ... -``` - -

Arguments

- -
REQUIREMENTS

The packages to add, as PEP 508 requirements (e.g., ruff==0.5.0)

- -
- -

Options

- -
--optional optional

Add the requirements to the specified optional dependency group

- -
--rev rev

Specific commit to use when adding from Git

- -
--tag tag

Tag to use when adding from git

- -
--branch branch

Branch to use when adding from git

- -
--extra extra

Extras to activate for the dependency; may be provided more than once

- -
--index-url, -i index-url

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

- -

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

- -

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

- -

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

- -

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

- -
--find-links, -f find-links

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

- -

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

- -
--upgrade-package, -P upgrade-package

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

- -
--reinstall-package reinstall-package

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

- -
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

- -

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

- -

Possible values:

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

Attempt to use keyring for authentication for index URLs.

- -

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

- -

Defaults to disabled.

- -

Possible values:

- -
    -
  • disabled: Do not use keyring for credential lookup
    • - -
  • subprocess: Use the keyring command for credential lookup
    • -
-
--resolution resolution

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

- -

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

- -

Possible values:

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

The strategy to use when considering pre-release versions.

- -

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

- -

Possible values:

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

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

- -
--exclude-newer exclude-newer

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

- -

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

- -
--link-mode link-mode

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

- -

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

- -

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

- -
--refresh-package refresh-package

Refresh cached data for a specific package

- -
--package package

Add the dependency to a specific package in the workspace

- -
--python, -p python

The Python interpreter into which packages should be installed.

- -

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

- -

Supported formats:

- -
    -
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • - -
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • - -
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • -
- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -## uv remove - -Remove one or more packages from the project's dependencies (experimental) - -

Usage

- -``` -uv remove [OPTIONS] ... -``` - -

Arguments

- -
REQUIREMENTS

The names of the packages to remove (e.g., ruff)

- -
- -

Options

- -
--optional optional

Remove the requirements from the specified optional dependency group

- -
--index-url, -i index-url

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

- -

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

- -

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

- -

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

- -

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

- -
--find-links, -f find-links

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

- -

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

- -
--upgrade-package, -P upgrade-package

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

- -
--reinstall-package reinstall-package

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

- -
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

- -

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

- -

Possible values:

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

Attempt to use keyring for authentication for index URLs.

- -

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

- -

Defaults to disabled.

- -

Possible values:

- -
    -
  • disabled: Do not use keyring for credential lookup
    • - -
  • subprocess: Use the keyring command for credential lookup
    • -
-
--resolution resolution

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

- -

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

- -

Possible values:

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

The strategy to use when considering pre-release versions.

- -

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

- -

Possible values:

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

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

- -
--exclude-newer exclude-newer

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

- -

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

- -
--link-mode link-mode

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

- -

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

- -

Possible values:

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

- -
--refresh-package refresh-package

Refresh cached data for a specific package

- -
--package package

Remove the dependency from a specific package in the workspace

- -
--python, -p python

The Python interpreter into which packages should be installed.

- -

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

- -

Supported formats:

- -
    -
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • - -
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • - -
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • -
- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- -## uv tree - -Display the dependency tree for the project (experimental) - -

Usage

- -``` -uv tree [OPTIONS] -``` - -

Options

- -
--depth, -d depth

Maximum display depth of the dependency tree

- -

[default: 255]

-
--prune prune

Prune the given package from the display of the dependency tree

- -
--package package

Display only the specified packages

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

Don’t build source distributions for a specific package

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

Don’t install pre-built wheels for a specific package

- -
--index-url, -i index-url

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

- -

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

- -

The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

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

- -

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

- -

All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

- -
--find-links, -f find-links

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

- -

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (.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.

- -
--upgrade-package, -P upgrade-package

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

- -
--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

- -

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

- -

Possible values:

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

Attempt to use keyring for authentication for index URLs.

- -

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

- -

Defaults to disabled.

- -

Possible values:

- -
    -
  • disabled: Do not use keyring for credential lookup
    • - -
  • subprocess: Use the keyring command for credential lookup
    • -
-
--resolution resolution

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

- -

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

- -

Possible values:

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

The strategy to use when considering pre-release versions.

- -

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

- -

Possible values:

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

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

- -
--exclude-newer exclude-newer

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

- -

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

- -
--link-mode link-mode

The 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, and hardlink on Linux and Windows.

- -

Possible values:

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

The Python version to use when filtering the tree (via --filter). For example, pass --python-version 3.10 to display the dependencies that would be included when installing on Python 3.10

- -
--python-platform python-platform

The platform to use when filtering the tree (via --filter). 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 or aaarch64-apple-darwin.

- -

Possible values:

- -
    -
  • windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
    • - -
  • linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
    • - -
  • macos: An alias for aarch64-apple-darwin, the default target for macOS
    • - -
  • x86_64-pc-windows-msvc: An x86 Windows target
    • - -
  • x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_17
    • - -
  • aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
    • - -
  • x86_64-apple-darwin: An x86 macOS target
    • - -
  • aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_17
    • - -
  • aarch64-unknown-linux-musl: An ARM64 Linux target
    • - -
  • x86_64-unknown-linux-musl: An x86_64 Linux target
    • - -
  • x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
    • - -
  • x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
    • - -
  • x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
    • - -
  • aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
    • - -
  • aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
    • - -
  • aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
    • -
-
--python, -p python

The Python interpreter for which packages should be listed.

- -

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

- -

Supported formats:

- -
    -
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • - -
  • python3.10 or python.exe looks for a binary with the given name in PATH.
    • - -
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • -
- -
--cache-dir cache-dir

Path to the cache directory.

- -

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

- -
--python-preference python-preference

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

- -

Possible values:

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

Whether to automatically download Python when required

- -

Possible values:

- -
    -
  • automatic: Automatically fetch managed Python installations when needed
    • - -
  • manual: Do not automatically fetch managed Python installations; require explicit installation
    • -
-
--color color-choice

Control colors in output

- -

[default: auto]

-

Possible values:

- -
    -
  • auto: Enables colored output only when the output is going to a terminal or TTY with support
    • - -
  • always: Enables colored output regardless of the detected environment
    • - -
  • never: Disables colored output
    • -
-
--config-file config-file

The path to a uv.toml file to use for configuration

- -
- ## uv venv Create a virtual environment @@ -3648,7 +3648,7 @@ uv venv [OPTIONS] [NAME] ## uv cache -Manage the cache +Manage uv's cache

Usage