From c28093c63be64bddda677b0beddc04aad9005646 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Thu, 1 Aug 2024 13:20:07 -0500 Subject: [PATCH] Unhide the experimental top-level commands --- crates/uv-cli/src/lib.rs | 7 - crates/uv/tests/help.rs | 49 +++ docs/reference/cli.md | 688 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 737 insertions(+), 7 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 22b3c5b1dbfb..b3862fee6624 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -416,45 +416,38 @@ pub enum PipCommand { #[derive(Subcommand)] pub enum ProjectCommand { /// Initialize a project. - #[clap(hide = true)] Init(InitArgs), /// Run a command in the project environment. - #[clap(hide = true)] #[command( after_help = "Use `uv help run` for more details.", after_long_help = "" )] Run(RunArgs), /// Sync the project's dependencies with the environment. - #[clap(hide = true)] #[command( after_help = "Use `uv help sync` for more details.", after_long_help = "" )] Sync(SyncArgs), /// Resolve the project requirements into a lockfile. - #[clap(hide = true)] #[command( after_help = "Use `uv help lock` for more details.", after_long_help = "" )] Lock(LockArgs), /// Add one or more packages to the project requirements. - #[clap(hide = true)] #[command( after_help = "Use `uv help add` for more details.", after_long_help = "" )] Add(AddArgs), /// Remove one or more packages from the project requirements. - #[clap(hide = true)] #[command( after_help = "Use `uv help remove` for more details.", after_long_help = "" )] Remove(RemoveArgs), /// Display the dependency tree for the project. - #[clap(hide = true)] Tree(TreeArgs), } diff --git a/crates/uv/tests/help.rs b/crates/uv/tests/help.rs index 5b455cd7b896..3c74f6627da3 100644 --- a/crates/uv/tests/help.rs +++ b/crates/uv/tests/help.rs @@ -19,6 +19,13 @@ fn help() { pip Resolve and install Python packages tool Run and manage executable Python packages python Manage Python installations + init Initialize a project + run Run a command in the project environment + sync Sync the project's dependencies with the environment + lock Resolve the project requirements into a lockfile + add Add one or more packages to the project requirements + remove Remove one or more packages from the project requirements + tree Display the dependency tree for the project venv Create a virtual environment cache Manage the cache version Display uv's version @@ -78,6 +85,13 @@ fn help_flag() { pip Resolve and install Python packages tool Run and manage executable Python packages python Manage Python installations + init Initialize a project + run Run a command in the project environment + sync Sync the project's dependencies with the environment + lock Resolve the project requirements into a lockfile + add Add one or more packages to the project requirements + remove Remove one or more packages from the project requirements + tree Display the dependency tree for the project venv Create a virtual environment cache Manage the cache version Display uv's version @@ -136,6 +150,13 @@ fn help_short_flag() { pip Resolve and install Python packages tool Run and manage executable Python packages python Manage Python installations + init Initialize a project + run Run a command in the project environment + sync Sync the project's dependencies with the environment + lock Resolve the project requirements into a lockfile + add Add one or more packages to the project requirements + remove Remove one or more packages from the project requirements + tree Display the dependency tree for the project venv Create a virtual environment cache Manage the cache version Display uv's version @@ -547,6 +568,13 @@ fn help_unknown_subcommand() { pip tool python + init + run + sync + lock + add + remove + tree venv cache version @@ -562,6 +590,13 @@ fn help_unknown_subcommand() { pip tool python + init + run + sync + lock + add + remove + tree venv cache version @@ -604,6 +639,13 @@ fn help_with_global_option() { pip Resolve and install Python packages tool Run and manage executable Python packages python Manage Python installations + init Initialize a project + run Run a command in the project environment + sync Sync the project's dependencies with the environment + lock Resolve the project requirements into a lockfile + add Add one or more packages to the project requirements + remove Remove one or more packages from the project requirements + tree Display the dependency tree for the project venv Create a virtual environment cache Manage the cache version Display uv's version @@ -699,6 +741,13 @@ fn help_with_no_pager() { pip Resolve and install Python packages tool Run and manage executable Python packages python Manage Python installations + init Initialize a project + run Run a command in the project environment + sync Sync the project's dependencies with the environment + lock Resolve the project requirements into a lockfile + add Add one or more packages to the project requirements + remove Remove one or more packages from the project requirements + tree Display the dependency tree for the project venv Create a virtual environment cache Manage the cache version Display uv's version diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 680d4596a4cd..a5cd15355f8b 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -18,6 +18,20 @@ uv [OPTIONS]
uv python

Manage Python installations

+
uv init

Initialize a project

+
+
uv run

Run a command in the project environment

+
+
uv sync

Sync the project’s dependencies with the environment

+
+
uv lock

Resolve the project requirements into a lockfile

+
+
uv add

Add one or more packages to the project requirements

+
+
uv remove

Remove one or more packages from the project requirements

+
+
uv tree

Display the dependency tree for the project

+
uv venv

Create a virtual environment

uv cache

Manage the cache

@@ -1316,6 +1330,680 @@ uv python uninstall [OPTIONS] ...
+## uv init + +Initialize a project + +

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

+ +
--python-fetch python-fetch

Whether to automatically download Python when required

+ +
--color color-choice

Control colors in output

+ +
--config-file config-file

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

+ +
+ +## uv run + +Run a command in the project environment + +

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.

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

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

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

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

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

+ +
--python-fetch python-fetch

Whether to automatically download Python when required

+ +
--color color-choice

Control colors in output

+ +
--config-file config-file

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

+ +
+ +## uv sync + +Sync the project's dependencies with the environment + +

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.

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

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

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

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

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

+ +
--python-fetch python-fetch

Whether to automatically download Python when required

+ +
--color color-choice

Control colors in output

+ +
--config-file config-file

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

+ +
+ +## uv lock + +Resolve the project requirements into a lockfile + +

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.

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

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

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

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

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

+ +
--python-fetch python-fetch

Whether to automatically download Python when required

+ +
--color color-choice

Control colors in 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 requirements + +

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.

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

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

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

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

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

+ +
--python-fetch python-fetch

Whether to automatically download Python when required

+ +
--color color-choice

Control colors in 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 requirements + +

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.

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

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

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

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

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

+ +
--python-fetch python-fetch

Whether to automatically download Python when required

+ +
--color color-choice

Control colors in 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 + +

Usage

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

Options

+ +
--depth, -d depth

Maximum display depth of the dependency tree

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

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

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

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

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

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

+ +
--python-fetch python-fetch

Whether to automatically download Python when required

+ +
--color color-choice

Control colors in output

+ +
--config-file config-file

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

+ +
+ ## uv venv Create a virtual environment