From 0341671c7105069a90fa1d5ea7ae17715fa4c238 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Tue, 6 Aug 2024 15:45:22 -0500 Subject: [PATCH] Improve display order of top-level commands --- crates/uv-cli/src/lib.rs | 52 +- crates/uv/tests/help.rs | 114 +-- docs/reference/cli.md | 1768 +++++++++++++++++++------------------- 3 files changed, 967 insertions(+), 967 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index f7ca04442711..a1b6b60bba10 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). + /// Create a new project (experimental). + Init(InitArgs), + /// Add dependencies to the project (experimental). #[command( - after_help = "Use `uv help sync` for more details.", + after_help = "Use `uv help add` for more details.", after_long_help = "" )] - Sync(SyncArgs), - /// Create or update a lockfile for the project's dependencies (experimental). + Add(AddArgs), + /// Remove dependencies from the project (experimental). #[command( - after_help = "Use `uv help lock` for more details.", + after_help = "Use `uv help remove` for more details.", after_long_help = "" )] - Lock(LockArgs), - /// Add one or more packages to the project's dependencies (experimental). + Remove(RemoveArgs), + /// Update the project's environment (experimental). #[command( - after_help = "Use `uv help add` for more details.", + after_help = "Use `uv help sync` for more details.", after_long_help = "" )] - Add(AddArgs), - /// Remove one or more packages from the project's dependencies (experimental). + Sync(SyncArgs), + /// Update the project's lockfile (experimental). #[command( - after_help = "Use `uv help remove` for more details.", + after_help = "Use `uv help lock` for more details.", after_long_help = "" )] - Remove(RemoveArgs), - /// Display the dependency tree for the project (experimental). + 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 7a2519973115..3c511d6e5087 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 c2b5f4db8db2..74cac68a0c88 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 tool

Run and manage tools provided by Python packages (experimental)

+
uv init

Create a new project (experimental)

-
uv python

Manage Python versions and installations (experimental)

+
uv add

Add dependencies to the project (experimental)

-
uv init

Create a new project (experimental)

+
uv remove

Remove dependencies from the project (experimental)

-
uv run

Run a command in an environment (experimental)

+
uv sync

Update the project’s environment (experimental)

-
uv sync

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

+
uv lock

Update the project’s lockfile (experimental)

-
uv lock

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

+
uv tree

Display the project’s dependency tree (experimental)

-
uv add

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

+
uv tool

Run and manage tools provided by Python packages (experimental)

-
uv remove

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

+
uv python

Manage Python versions and installations (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,79 +42,27 @@ uv [OPTIONS]
-## uv pip - -Manage Python packages with a pip-compatible interface - -

Usage

- -``` -uv pip [OPTIONS] -``` - -

Commands

- -
uv pip compile

Compile a requirements.in file to a requirements.txt file

-
-
uv pip sync

Sync an environment with a requirements.txt file

-
-
uv pip install

Install packages into an environment

-
-
uv pip uninstall

Uninstall packages from an environment

-
-
uv pip freeze

List, in requirements format, packages installed in an environment

-
-
uv pip list

List, in tabular format, packages installed in an environment

-
-
uv pip show

Show information about one or more installed packages

-
-
uv pip tree

Display the dependency tree for an environment

-
-
uv pip check

Verify installed packages have compatible dependencies

-
-
- -### uv pip compile +## uv run -Compile a `requirements.in` file to a `requirements.txt` file +Run a command or script (experimental)

Usage

``` -uv pip compile [OPTIONS] ... +uv run [OPTIONS] ``` -

Arguments

- -
SRC_FILE

Include all packages listed in the given requirements.in files.

- -

If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.

- -

If - is provided, then requirements will be read from stdin.

- -
-

Options

-
--constraint, -c constraint

Constrain versions using the given requirements files.

- -

Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

- -

This is equivalent to pip’s --constraint option.

- -
--override override

Override versions using the given requirements files.

- -

Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.

- -

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

+
--extra extra

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

-
--build-constraint, -b build-constraint

Constrain build dependencies using the given requirements files when building source distributions.

+

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

-

Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

+
--with with

Run with the given packages installed

-
--extra extra

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

+
--with-requirements with-requirements

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

-

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

+

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

@@ -136,6 +84,8 @@ uv pip compile [OPTIONS] ...
--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.

@@ -200,8 +150,6 @@ uv pip compile [OPTIONS] ...
--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:

@@ -215,28 +163,15 @@ uv pip compile [OPTIONS] ...
  • symlink: Symbolically link packages from the wheel into the site-packages directory
    • -
    --refresh-package refresh-package

    Refresh cached data for a specific package

    - -
    --output-file, -o output-file

    Write the compiled requirements to the given requirements.txt file.

    - -

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

    - -
    --annotation-style annotation-style

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

    - -

    Defaults to split.

    - -

    Possible values:

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

    Don’t build source distributions for a specific package

    -
      -
    • line: Render the annotations on a single, comma-separated line
      • +
    --no-binary-package no-binary-package

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

    -
  • split: Render each annotation on its own line
    • - -
    --custom-compile-command custom-compile-command

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

    +
    --refresh-package refresh-package

    Refresh cached data for a specific package

    -

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

    +
    --package package

    Run the command in a specific package in the workspace

    -
    --python python

    The Python interpreter against which to compile the requirements.

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

    @@ -250,62 +185,81 @@ uv pip compile [OPTIONS] ...
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • -
    --no-binary no-binary

    Don’t install pre-built wheels.

    +
    --cache-dir cache-dir

    Path to the cache directory.

    -

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

    +

    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.

    -

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

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

    -
    --only-binary only-binary

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

    +

    Possible values:

    -

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

    +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • -

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

      +
    • managed: Prefer managed Python installations over system Python installations
      • -
    --python-version, -p python-version

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

    +
  • system: Prefer system Python installations over managed Python installations
    • -

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

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

    Whether to automatically download Python when required

    -
    --python-platform python-platform

    The platform for which requirements should be resolved.

    +

    Possible values:

    -

    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.

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

      -
    • windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
      • +
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • -
    • linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
      • +
    • always: Enables colored output regardless of the detected environment
      • -
    • macos: An alias for aarch64-apple-darwin, the default target for macOS
      • +
    • never: Disables colored output
      • +
    +
    --config-file config-file

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

    -
  • 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
    • +## uv init -
  • aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
    • +Create a new project (experimental) -
  • x86_64-apple-darwin: An x86 macOS target
    • +

    Usage

    -
  • aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_17
    • +``` +uv init [OPTIONS] [PATH] +``` -
  • aarch64-unknown-linux-musl: An ARM64 Linux target
    • +

    Arguments

    -
  • x86_64-unknown-linux-musl: An x86_64 Linux target
    • +
    PATH

    The path of the project

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

    Options

    -
  • x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
    • +
    --name name

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

    -
  • aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
    • +
    --python, -p python

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

    -
  • aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
    • +

    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.

    -
  • aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
    • +

    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.
    -
    --no-emit-package no-emit-package

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

    --cache-dir cache-dir

    Path to the cache directory.

    @@ -349,37 +303,33 @@ uv pip compile [OPTIONS] ...
    -### uv pip sync +## uv add -Sync an environment with a `requirements.txt` file +Add dependencies to the project (experimental)

    Usage

    ``` -uv pip sync [OPTIONS] ... +uv add [OPTIONS] ... ```

    Arguments

    -
    SRC_FILE

    Include all packages listed in the given requirements.txt files.

    - -

    If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.

    - -

    If - is provided, then requirements will be read from stdin.

    +
    REQUIREMENTS

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

    Options

    -
    --constraint, -c constraint

    Constrain versions using the given requirements files.

    +
    --optional optional

    Add the requirements to the specified optional dependency group

    -

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

    +
    --rev rev

    Specific commit to use when adding from Git

    -

    This is equivalent to pip’s --constraint option.

    +
    --tag tag

    Tag to use when adding from git

    -
    --build-constraint, -b build-constraint

    Constrain build dependencies using the given requirements files when building source distributions.

    +
    --branch branch

    Branch to use when adding from git

    -

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

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

    @@ -399,6 +349,8 @@ uv pip sync [OPTIONS] ...

    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.

    @@ -427,6 +379,36 @@ uv pip sync [OPTIONS] ...
  • 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.

    @@ -448,8 +430,14 @@ uv pip sync [OPTIONS] ...
  • 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.

    @@ -464,92 +452,29 @@ uv pip sync [OPTIONS] ...
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • -
    --target target

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

    +
    --cache-dir cache-dir

    Path to the cache directory.

    -
    --prefix prefix

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

    +

    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.

    -

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

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

    -
    --no-binary no-binary

    Don’t install pre-built wheels.

    +

    Possible values:

    -

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

    +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • -

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

      +
    • managed: Prefer managed Python installations over system Python installations
      • -
    --only-binary only-binary

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

    +
  • system: Prefer system Python installations over managed Python installations
    • -

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

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

    Whether to automatically download Python when required

    -

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

    +

    Possible values:

    -
    --python-version python-version

    The minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).

    - -

    If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.

    - -
    --python-platform python-platform

    The platform for which requirements should be installed.

    - -

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

    - -

    WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

    - -

    Possible values:

    - -
      -
    • windows: An alias 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
      • -
    -
    --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
      • +
        +
      • automatic: Automatically fetch managed Python installations when needed
      • manual: Do not automatically fetch managed Python installations; require explicit installation
      @@ -569,51 +494,25 @@ uv pip sync [OPTIONS] ...
    -### uv pip install +## uv remove -Install packages into an environment +Remove dependencies from the project (experimental)

    Usage

    ``` -uv pip install [OPTIONS] |--editable > +uv remove [OPTIONS] ... ```

    Arguments

    -
    PACKAGE

    Install all listed packages

    +
    REQUIREMENTS

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

    Options

    -
    --requirement, -r requirement

    Install all packages listed in the given requirements.txt files.

    - -

    If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.

    - -

    If - is provided, then requirements will be read from stdin.

    - -
    --editable, -e editable

    Install the editable package based on the provided local file path

    - -
    --constraint, -c constraint

    Constrain versions using the given requirements files.

    - -

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

    - -

    This is equivalent to pip’s --constraint option.

    - -
    --override override

    Override versions using the given requirements files.

    - -

    Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.

    - -

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

    - -
    --build-constraint, -b build-constraint

    Constrain build dependencies using the given requirements files when building source distributions.

    - -

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

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

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

    @@ -714,8 +613,14 @@ uv pip install [OPTIONS] |--editable 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.

    @@ -730,69 +635,6 @@ uv pip install [OPTIONS] |--editable /home/ferris/.local/bin/python3.10 uses the exact Python at the given path. -
    --target target

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

    - -
    --prefix prefix

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

    - -

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

    - -
    --no-binary no-binary

    Don’t install pre-built wheels.

    - -

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

    - -

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

    - -
    --only-binary only-binary

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

    - -

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

    - -

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

    - -
    --python-version python-version

    The minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).

    - -

    If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.

    - -
    --python-platform python-platform

    The platform for which requirements should be installed.

    - -

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

    - -

    WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

    - -

    Possible values:

    - -
      -
    • windows: An alias 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
      • -
    --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.

    @@ -835,41 +677,58 @@ uv pip install [OPTIONS] |--editable
    -### uv pip uninstall +## uv sync -Uninstall packages from an environment +Update the project's environment (experimental)

    Usage

    ``` -uv pip uninstall [OPTIONS] > +uv sync [OPTIONS] ``` -

    Arguments

    +

    Options

    -
    PACKAGE

    Uninstall all listed packages

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

    -

    Options

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

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

    -
    --requirement, -r requirement

    Uninstall all packages listed in the given requirements files

    +

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

    -
    --python, -p python

    The Python interpreter from which packages should be uninstalled.

    +

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

    -

    By default, uv uninstalls from 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.

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

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

    -

    Supported formats:

    +

    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:

      -
    • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
      • +
    • first-index: Only use results from the first index that returns a match for a given package name
      • -
    • python3.10 or python.exe looks for a binary with the given name in PATH.
      • +
    • unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
      • -
    • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
      • +
    • 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 remote requirements files.

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

    @@ -882,67 +741,68 @@ uv pip uninstall [OPTIONS] >
  • subprocess: Use the keyring command for credential lookup
    • -
    --target target

    Uninstall packages from the specified --target directory

    - -
    --prefix prefix

    Uninstall packages from the specified --prefix directory

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

    +
    --resolution resolution

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

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

    +

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

    Possible values:

      -
    • only-managed: Only use managed Python installations; never use system Python installations
      • - -
    • managed: Prefer managed Python installations over system Python installations
      • +
    • highest: Resolve the highest compatible version of each package
      • -
    • system: Prefer system Python installations over managed Python installations
      • +
    • lowest: Resolve the lowest compatible version of each package
      • -
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    • lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
    -
    --python-fetch python-fetch

    Whether to automatically download Python when required

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

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

    +
  • disallow: Disallow all pre-release versions
    • -

    [default: auto]

    -

    Possible values:

    +
  • allow: Allow all pre-release versions
    • -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +
    • if-necessary: Allow pre-release versions if all versions of a package are pre-release
      • -
    • always: Enables colored output regardless of the detected environment
      • +
    • explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
      • -
    • never: Disables colored output
      • +
    • 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-file config-file

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

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

    -### uv pip freeze +

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

    -List, in requirements format, packages installed in an environment +
    --link-mode link-mode

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

    -

    Usage

    +

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

    -``` -uv pip freeze [OPTIONS] -``` +

    Possible values:

    -

    Options

    +
      +
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • -
      --python, -p python

      The Python interpreter for which packages should be listed.

      +
    • copy: Copy packages from the wheel into the site-packages directory
      • -

      By default, uv lists packages in the currently activated virtual environment, or a virtual environment (.venv) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.

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

    @@ -996,109 +856,126 @@ uv pip freeze [OPTIONS]
    -### uv pip list +## uv lock -List, in tabular format, packages installed in an environment +Update the project's lockfile (experimental)

    Usage

    ``` -uv pip list [OPTIONS] +uv lock [OPTIONS] ```

    Options

    -
    --exclude exclude

    Exclude the specified package(s) from the output

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

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

    -
    --format format

    Select the output format between: columns (default), freeze, or json

    +

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

    -

    [default: columns]

    -

    Possible values:

    +

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

    -
      -
    • columns: Display the list of packages in a human-readable table
      • +
    --extra-index-url extra-index-url

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

    -
  • freeze: Display the list of packages in a pip freeze-like format, with one package per line alongside its version
    • +

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

    -
  • json: Display the list of packages in a machine-readable JSON format
    • - -
    --python, -p python

    The Python interpreter for which packages should be listed.

    +

    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.

    -

    By default, uv lists packages in the currently activated virtual environment, or a virtual environment (.venv) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.

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

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

    -

    Supported formats:

    +

    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:

      -
    • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
      • +
    • first-index: Only use results from the first index that returns a match for a given package name
      • -
    • python3.10 or python.exe looks for a binary with the given name in PATH.
      • +
    • unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
      • -
    • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
      • +
    • 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.

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

    +

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

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

    +

    Defaults to disabled.

    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
      • +
    • disabled: Do not use keyring for credential lookup
      • -
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    • subprocess: Use the keyring command for credential lookup
    -
    --python-fetch python-fetch

    Whether to automatically download Python when required

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

      -
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • highest: Resolve the highest compatible version of each package
      • -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    • 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
    -
    --color color-choice

    Control colors in output

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

    -

    [default: auto]

    Possible values:

      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +
    • disallow: Disallow all pre-release versions
      • -
    • always: Enables colored output regardless of the detected environment
      • +
    • allow: Allow all pre-release versions
      • -
    • never: Disables colored output
      • +
    • 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-file config-file

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

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

    -### uv pip show +

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

    -Show information about one or more installed packages +
    --link-mode link-mode

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

    -

    Usage

    +

    This option is only used when building source distributions.

    -``` -uv pip show [OPTIONS] [PACKAGE]... -``` +

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

    -

    Arguments

    +

    Possible values:

    -
    PACKAGE

    The package(s) to display

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

    Options

    +
  • hardlink: Hard link packages from the wheel into the site-packages directory
    • -
    --python, -p python

    The Python interpreter for which packages should be listed.

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

    -

    By default, uv lists packages in the currently activated virtual environment, or a virtual environment (.venv) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.

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

    @@ -1152,14 +1029,14 @@ uv pip show [OPTIONS] [PACKAGE]...
    -### uv pip tree +## uv tree -Display the dependency tree for an environment +Display the project's dependency tree (experimental)

    Usage

    ``` -uv pip tree [OPTIONS] +uv tree [OPTIONS] ```

    Options

    @@ -1171,100 +1048,176 @@ uv pip tree [OPTIONS]
    --package package

    Display only the specified packages

    -
    --python, -p python

    The Python interpreter for which packages should be listed.

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

    Don’t build source distributions for a specific package

    -

    By default, uv lists packages in the currently activated virtual environment, or a virtual environment (.venv) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.

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

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

    -

    Supported formats:

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

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

    -
      -
    • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
      • +

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

      -
    • python3.10 or python.exe looks for a binary with the given name in PATH.
      • +

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

      -
    • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
      • -
    +
    --extra-index-url extra-index-url

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

    -
    --cache-dir cache-dir

    Path to the cache directory.

    +

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

    -

    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.

    +

    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.

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

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

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

    -

    Possible values:

    +

    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.

    -
      -
    • only-managed: Only use managed Python installations; never use system Python installations
      • +

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

      -
    • managed: Prefer managed Python installations over system Python installations
      • +
    --upgrade-package, -P upgrade-package

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

    -
  • system: Prefer system Python installations over managed Python installations
    • +
    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

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

    Whether to automatically download Python when required

    +

    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:

      -
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • first-index: Only use results from the first index that returns a match for a given package name
      • -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    • 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
    -
    --color color-choice

    Control colors in output

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

    -

    [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
      • +
    • disabled: Do not use keyring for credential lookup
      • -
    • never: Disables colored output
      • +
    • subprocess: Use the keyring command for credential lookup
    -
    --config-file config-file

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

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

    -### uv pip check +

    Possible values:

    -Verify installed packages have compatible dependencies +
      +
    • highest: Resolve the highest compatible version of each package
      • -

      Usage

      +
    • lowest: Resolve the lowest compatible version of each package
      • -``` -uv pip check [OPTIONS] -``` +
    • 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.

    -

    Options

    +

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

    -
    --python, -p python

    The Python interpreter for which packages should be listed.

    +

    Possible values:

    -

    By default, uv lists packages in the currently activated virtual environment, or a virtual environment (.venv) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.

    +
      +
    • disallow: Disallow all pre-release versions
      • -

      Supported formats:

      +
    • allow: Allow all pre-release versions
      • -
        -
      • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
        • +
      • if-necessary: Allow pre-release versions if all versions of a package are pre-release
        • -
      • python3.10 or python.exe looks for a binary with the given name in PATH.
        • +
      • explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
        • -
      • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
        • +
      • 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

    -
    --cache-dir cache-dir

    Path to the cache directory.

    +
    --exclude-newer exclude-newer

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

    -

    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.

    +

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

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

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

      -
    • only-managed: Only use managed Python installations; never use system Python installations
      • +
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • -
    • managed: Prefer managed Python installations over system Python installations
      • +
    • 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
      • @@ -2283,104 +2236,80 @@ uv python uninstall [OPTIONS] ...
    -## uv init +## uv pip -Create a new project (experimental) +Manage Python packages with a pip-compatible interface

    Usage

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

    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.

    +

    Commands

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

    +
    uv pip compile

    Compile a requirements.in file to a requirements.txt file

    +
    +
    uv pip sync

    Sync an environment with a requirements.txt file

    +
    +
    uv pip install

    Install packages into an environment

    +
    +
    uv pip uninstall

    Uninstall packages from an environment

    +
    +
    uv pip freeze

    List, in requirements format, packages installed in an environment

    +
    +
    uv pip list

    List, in tabular format, packages installed in an environment

    +
    +
    uv pip show

    Show information about one or more installed packages

    +
    +
    uv pip tree

    Display the dependency tree for an environment

    +
    +
    uv pip check

    Verify installed packages have compatible dependencies

    +
    +
    -

    Possible values:

    +### uv pip compile -
      -
    • only-managed: Only use managed Python installations; never use system Python installations
      • +Compile a `requirements.in` file to a `requirements.txt` file -
    • managed: Prefer managed Python installations over system Python installations
      • +

      Usage

      -
    • system: Prefer system Python installations over managed Python installations
      • +``` +uv pip compile [OPTIONS] ... +``` -
    • only-system: Only use system Python installations; never use managed Python installations
      • -
    -
    --python-fetch python-fetch

    Whether to automatically download Python when required

    +

    Arguments

    -

    Possible values:

    +
    SRC_FILE

    Include all packages listed in the given requirements.in files.

    -
      -
    • automatic: Automatically fetch managed Python installations when needed
      • +

      If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.

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

    Control colors in output

    +

    If - is provided, then requirements will be read from stdin.

    -

    [default: auto]

    -

    Possible values:

    +
    -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +

      Options

      -
    • always: Enables colored output regardless of the detected environment
      • +
      --constraint, -c constraint

      Constrain versions using the given requirements files.

      -
    • never: Disables colored output
      • -
    -
    --config-file config-file

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

    +

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

    -
    +

    This is equivalent to pip’s --constraint option.

    -## uv run +
    --override override

    Override versions using the given requirements files.

    -Run a command in an environment (experimental) +

    Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.

    -

    Usage

    +

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

    -``` -uv run [OPTIONS] -``` +
    --build-constraint, -b build-constraint

    Constrain build dependencies using the given requirements files when building source distributions.

    -

    Options

    +

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

    -
    --extra extra

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

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

    @@ -2401,8 +2330,6 @@ uv run [OPTIONS]
    --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.

    @@ -2467,6 +2394,8 @@ uv run [OPTIONS]
    --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:

    @@ -2480,15 +2409,28 @@ uv run [OPTIONS]
  • 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

    +
    --refresh-package refresh-package

    Refresh cached data for a specific package

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

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

    +
    --output-file, -o output-file

    Write the compiled requirements to the given requirements.txt file.

    -
    --refresh-package refresh-package

    Refresh cached data for a specific package

    +

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

    -
    --package package

    Run the command in a specific package in the workspace

    +
    --annotation-style annotation-style

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

    -
    --python, -p python

    The Python interpreter to use to build the run environment.

    +

    Defaults to split.

    + +

    Possible values:

    + +
      +
    • line: Render the annotations on a single, comma-separated line
      • + +
    • split: Render each annotation on its own line
      • +
    +
    --custom-compile-command custom-compile-command

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

    + +

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

    + +
    --python python

    The Python interpreter against which to compile the requirements.

    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.

    @@ -2502,63 +2444,136 @@ uv run [OPTIONS]
  • /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.

    +
    --no-binary no-binary

    Don’t install pre-built wheels.

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

    +

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

    -

    Possible values:

    +

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

    -
      -
    • only-managed: Only use managed Python installations; never use system Python installations
      • +
    --only-binary only-binary

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

    -
  • managed: Prefer managed Python installations over system Python installations
    • +

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

    -
  • system: Prefer system Python installations over managed Python installations
    • +

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

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

    Whether to automatically download Python when required

    +
    --python-version, -p python-version

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

    -

    Possible values:

    +

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

    -
      -
    • automatic: Automatically fetch managed Python installations when needed
      • +
    --python-platform python-platform

    The platform for which requirements should be resolved.

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

    Control colors in output

    +

    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.

    -

    [default: auto]

    Possible values:

      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +
    • windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
      • -
    • always: Enables colored output regardless of the detected environment
      • +
    • linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
      • -
    • never: Disables colored output
      • -
    -
    --config-file config-file

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

    +
  • macos: An alias for aarch64-apple-darwin, the default target for macOS
    • -
    +
  • x86_64-pc-windows-msvc: An x86 Windows target
    • -## uv sync +
  • x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_17
    • -Update the project's environment to match the project's dependencies (experimental) +
  • aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
    • -

    Usage

    +
  • 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
    • + +
    --no-emit-package no-emit-package

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

    + +
    --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 sync + +Sync an environment with a `requirements.txt` file + +

    Usage

    + +``` +uv pip sync [OPTIONS] ... ``` -uv sync [OPTIONS] -``` + +

    Arguments

    + +
    SRC_FILE

    Include all packages listed in the given requirements.txt files.

    + +

    If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.

    + +

    If - is provided, then requirements will be read from stdin.

    + +

    Options

    -
    --extra extra

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

    +
    --constraint, -c constraint

    Constrain versions using the given requirements files.

    -

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

    +

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

    + +

    This is equivalent to pip’s --constraint option.

    + +
    --build-constraint, -b build-constraint

    Constrain build dependencies using the given requirements files when building source distributions.

    + +

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

    --index-url, -i index-url

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

    @@ -2578,8 +2593,6 @@ uv sync [OPTIONS]

    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.

    @@ -2608,79 +2621,106 @@ uv sync [OPTIONS]
  • 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.

    +
    --config-setting, -C config-setting

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

    -

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

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

      -
    • highest: Resolve the highest compatible version of each package
      • +
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • -
    • lowest: Resolve the lowest compatible version of each package
      • +
    • copy: Copy packages from the wheel into the site-packages directory
      • -
    • lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
      • +
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • + +
    • symlink: Symbolically link packages from the wheel into the site-packages directory
    -
    --prerelease prerelease

    The strategy to use when considering pre-release versions.

    +
    --refresh-package refresh-package

    Refresh cached data for a specific package

    -

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

    +
    --python, -p python

    The Python interpreter into which packages should be installed.

    -

    Possible values:

    +

    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:

      -
    • disallow: Disallow all pre-release versions
      • +
    • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
      • -
    • allow: Allow all pre-release versions
      • +
    • python3.10 or python.exe looks for a binary with the given name in PATH.
      • -
    • if-necessary: Allow pre-release versions if all versions of a package are pre-release
      • +
    • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
      • +
    -
  • explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
    • +
    --target target

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

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

    +
    --prefix prefix

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

    -
    --exclude-newer exclude-newer

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

    +

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

    -

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

    +
    --no-binary no-binary

    Don’t install pre-built wheels.

    -
    --link-mode link-mode

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

    +

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

    -

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

    +

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

    + +
    --only-binary only-binary

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

    + +

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

    + +

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

    + +
    --python-version python-version

    The minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).

    + +

    If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.

    + +
    --python-platform python-platform

    The platform for which requirements should be installed.

    + +

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

    + +

    WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

    Possible values:

      -
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • +
    • windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
      • -
    • copy: Copy packages from the wheel into the site-packages directory
      • +
    • linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
      • -
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • +
    • macos: An alias for aarch64-apple-darwin, the default target for macOS
      • -
    • 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

    +
  • x86_64-pc-windows-msvc: An x86 Windows target
    • -
    --no-binary-package no-binary-package

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

    +
  • x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_17
    • -
    --refresh-package refresh-package

    Refresh cached data for a specific package

    +
  • aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
    • -
    --package package

    Sync a specific package in the workspace

    +
  • x86_64-apple-darwin: An x86 macOS target
    • -
    --python, -p python

    The Python interpreter to use to build the run environment.

    +
  • aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_17
    • -

    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.

    +
  • aarch64-unknown-linux-musl: An ARM64 Linux target
    • -

    Supported formats:

    +
  • x86_64-unknown-linux-musl: An x86_64 Linux target
    • -
      -
    • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
      • +
    • x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
      • -
    • python3.10 or python.exe looks for a binary with the given name in PATH.
      • +
    • x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
      • -
    • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
      • -
    +
  • 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
    • +
    --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.

    @@ -2723,19 +2763,53 @@ uv sync [OPTIONS]
    -## uv lock +### uv pip install -Create or update a lockfile for the project's dependencies (experimental) +Install packages into an environment

    Usage

    ``` -uv lock [OPTIONS] +uv pip install [OPTIONS] |--editable > ``` +

    Arguments

    + +
    PACKAGE

    Install all listed packages

    + +
    +

    Options

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

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

    +
    --requirement, -r requirement

    Install all packages listed in the given requirements.txt files.

    + +

    If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.

    + +

    If - is provided, then requirements will be read from stdin.

    + +
    --editable, -e editable

    Install the editable package based on the provided local file path

    + +
    --constraint, -c constraint

    Constrain versions using the given requirements files.

    + +

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

    + +

    This is equivalent to pip’s --constraint option.

    + +
    --override override

    Override versions using the given requirements files.

    + +

    Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.

    + +

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

    + +
    --build-constraint, -b build-constraint

    Constrain build dependencies using the given requirements files when building source distributions.

    + +

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

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

    @@ -2755,6 +2829,8 @@ uv lock [OPTIONS]
    --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.

    @@ -2819,8 +2895,6 @@ uv lock [OPTIONS]
    --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:

    @@ -2834,15 +2908,11 @@ uv lock [OPTIONS]
  • 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.

    +
    --python, -p python

    The Python interpreter into which packages should be installed.

    -

    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.

    +

    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:

    @@ -2854,16 +2924,79 @@ uv lock [OPTIONS]
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • -
    --cache-dir cache-dir

    Path to the cache directory.

    +
    --target target

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

    -

    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.

    +
    --prefix prefix

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

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

    +

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

    -

    Possible values:

    +
    --no-binary no-binary

    Don’t install pre-built wheels.

    -
      -
    • only-managed: Only use managed Python installations; never use system Python installations
      • +

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

      + +

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

      + +
    --only-binary only-binary

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

    + +

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

    + +

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

    + +
    --python-version python-version

    The minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).

    + +

    If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.

    + +
    --python-platform python-platform

    The platform for which requirements should be installed.

    + +

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

    + +

    WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

    + +

    Possible values:

    + +
      +
    • windows: An alias 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
      • +
    +
    --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
      • @@ -2896,70 +3029,41 @@ uv lock [OPTIONS]
    -## uv add +### uv pip uninstall -Add one or more packages to the project's dependencies (experimental) +Uninstall packages from an environment

    Usage

    ``` -uv add [OPTIONS] ... +uv pip uninstall [OPTIONS] > ```

    Arguments

    -
    REQUIREMENTS

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

    +
    PACKAGE

    Uninstall all listed packages

    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

    +
    --requirement, -r requirement

    Uninstall all packages listed in the given requirements files

    -
    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    +
    --python, -p python

    The Python interpreter from which packages should be uninstalled.

    -

    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.

    +

    By default, uv uninstalls from 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.

    -

    Possible values:

    +

    Supported formats:

      -
    • first-index: Only use results from the first index that returns a match for a given package name
      • +
    • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
      • -
    • unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
      • +
    • python3.10 or python.exe looks for a binary with the given name in PATH.
      • -
    • 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
      • +
    • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    -
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    + +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for remote requirements files.

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

    @@ -2972,68 +3076,67 @@ uv add [OPTIONS] ...
  • 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:

    +
    --target target

    Uninstall packages from the specified --target directory

    -
      -
    • highest: Resolve the highest compatible version of each package
      • +
    --prefix prefix

    Uninstall packages from the specified --prefix directory

    -
  • lowest: Resolve the lowest compatible version of each package
    • +
    --cache-dir cache-dir

    Path to the cache directory.

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

    +

    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.

    -

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

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

      -
    • disallow: Disallow all pre-release versions
      • - -
    • allow: Allow all pre-release versions
      • +
    • only-managed: Only use managed Python installations; never use system Python installations
      • -
    • if-necessary: Allow pre-release versions if all versions of a package are pre-release
      • +
    • managed: Prefer managed Python installations over system Python installations
      • -
    • explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
      • +
    • system: Prefer system Python installations over managed Python installations
      • -
    • 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
      • +
    • only-system: Only use system Python installations; never use managed Python installations
    -
    --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.

    +
    --python-fetch python-fetch

    Whether to automatically download Python when required

    -

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

    +

    Possible values:

    -
    --link-mode link-mode

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

    +
      +
    • automatic: Automatically fetch managed Python installations when needed
      • -

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

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

    Control colors in output

    +

    [default: auto]

    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
      • +
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • -
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • +
    • always: Enables colored output regardless of the detected environment
      • -
    • symlink: Symbolically link packages from the wheel into the site-packages directory
      • +
    • never: Disables colored output
    -
    --no-build-package no-build-package

    Don’t build source distributions for a specific package

    +
    --config-file config-file

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

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

    +### uv pip freeze -
    --package package

    Add the dependency to a specific package in the workspace

    +List, in requirements format, packages installed in an environment -
    --python, -p python

    The Python interpreter into which packages should be installed.

    +

    Usage

    -

    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.

    +``` +uv pip freeze [OPTIONS] +``` + +

    Options

    + +
    --python, -p python

    The Python interpreter for which packages should be listed.

    + +

    By default, uv lists packages in the currently activated virtual environment, or a virtual environment (.venv) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.

    Supported formats:

    @@ -3087,136 +3190,109 @@ uv add [OPTIONS] ...
    -## uv remove +### uv pip list -Remove one or more packages from the project's dependencies (experimental) +List, in tabular format, packages installed in an environment

    Usage

    ``` -uv remove [OPTIONS] ... +uv pip list [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

    +
    --exclude exclude

    Exclude the specified package(s) from the output

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

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

    +
    --format format

    Select the output format between: columns (default), freeze, or json

    -

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

    +

    [default: columns]

    +

    Possible values:

    -

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

    +
      +
    • columns: Display the list of packages in a human-readable table
      • -
    --extra-index-url extra-index-url

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

    +
  • freeze: Display the list of packages in a pip freeze-like format, with one package per line alongside its version
    • -

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

    +
  • json: Display the list of packages in a machine-readable JSON format
    • + +
    --python, -p python

    The Python interpreter for which packages should be listed.

    -

    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.

    +

    By default, uv lists packages in the currently activated virtual environment, or a virtual environment (.venv) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.

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

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

    +

    Supported formats:

    -

    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.

    +
      +
    • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
      • -

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

      +
    • python3.10 or python.exe looks for a binary with the given name in PATH.
      • -
    --upgrade-package, -P upgrade-package

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

    +
  • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    • + -
    --reinstall-package reinstall-package

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

    +
    --cache-dir cache-dir

    Path to the cache directory.

    -
    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    +

    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.

    -

    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.

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

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

    +
  • only-managed: Only use managed Python installations; never use system Python installations
    • -

    Possible values:

    +
  • managed: Prefer managed Python installations over system Python installations
    • -
      -
    • disabled: Do not use keyring for credential lookup
      • +
    • system: Prefer system Python installations over managed Python installations
      • -
    • subprocess: Use the keyring command for credential lookup
      • +
    • only-system: Only use system Python installations; never use managed Python installations
    -
    --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).

    +
    --python-fetch python-fetch

    Whether to automatically download Python when required

    Possible values:

      -
    • highest: Resolve the highest compatible version of each package
      • - -
    • lowest: Resolve the lowest compatible version of each package
      • +
    • automatic: Automatically fetch managed Python installations when needed
      • -
    • lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
      • +
    • manual: Do not automatically fetch managed Python installations; require explicit installation
    -
    --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).

    +
    --color color-choice

    Control colors in output

    +

    [default: auto]

    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
      • +
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • -
    • explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
      • +
    • always: Enables colored output regardless of the detected environment
      • -
    • 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
      • +
    • never: Disables colored output
    -
    --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.

    +
    --config-file config-file

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

    -

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

    +
    -

    Possible values:

    +### uv pip show -
      -
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • +Show information about one or more installed packages -
    • copy: Copy packages from the wheel into the site-packages directory
      • +

      Usage

      -
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • +``` +uv pip show [OPTIONS] [PACKAGE]... +``` -
    • 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

    +

    Arguments

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

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

    +
    PACKAGE

    The package(s) to display

    -
    --refresh-package refresh-package

    Refresh cached data for a specific package

    +
    -
    --package package

    Remove the dependency from a specific package in the workspace

    +

    Options

    -
    --python, -p python

    The Python interpreter into which packages should be installed.

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

    +

    By default, uv lists packages in the currently activated virtual environment, or a virtual environment (.venv) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.

    Supported formats:

    @@ -3270,14 +3346,14 @@ uv remove [OPTIONS] ...
    -## uv tree +### uv pip tree -Display the dependency tree for the project (experimental) +Display the dependency tree for an environment

    Usage

    ``` -uv tree [OPTIONS] +uv pip tree [OPTIONS] ```

    Options

    @@ -3289,153 +3365,77 @@ uv tree [OPTIONS]
    --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.

    +
    --python, -p python

    The Python interpreter for which packages should be listed.

    -

    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.

    +

    By default, uv lists packages in the currently activated virtual environment, or a virtual environment (.venv) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.

    -

    Possible values:

    +

    Supported formats:

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

    +
  • 3.10 looks for an installed Python 3.10 using py --list-paths on Windows, or python3.10 on Linux and macOS.
    • -
      -
    • disabled: Do not use keyring for credential lookup
      • +
    • python3.10 or python.exe looks for a binary with the given name in PATH.
      • -
    • subprocess: Use the keyring command for credential lookup
      • +
    • /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.
    -
    --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
      • +
    --cache-dir cache-dir

    Path to the cache directory.

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

    +

    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.

    -

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

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

      -
    • disallow: Disallow all pre-release versions
      • - -
    • allow: Allow all pre-release versions
      • +
    • only-managed: Only use managed Python installations; never use system Python installations
      • -
    • if-necessary: Allow pre-release versions if all versions of a package are pre-release
      • +
    • managed: Prefer managed Python installations over system Python installations
      • -
    • explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
      • +
    • system: Prefer system Python installations over managed Python installations
      • -
    • 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
      • +
    • only-system: Only use system Python installations; never use managed Python installations
    -
    --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-fetch python-fetch

    Whether to automatically download Python when required

    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
      • +
    • automatic: Automatically fetch managed Python installations when needed
      • -
    • symlink: Symbolically link packages from the wheel into the site-packages directory
      • +
    • manual: Do not automatically fetch managed Python installations; require explicit installation
    -
    --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.

    +
    --color color-choice

    Control colors in output

    +

    [default: auto]

    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
      • +
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • -
    • aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_17
      • +
    • always: Enables colored output regardless of the detected environment
      • -
    • aarch64-unknown-linux-musl: An ARM64 Linux target
      • +
    • never: Disables colored output
      • +
    +
    --config-file config-file

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

    -
  • 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
    • +### uv pip check -
  • x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
    • +Verify installed packages have compatible dependencies -
  • x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
    • +

    Usage

    -
  • aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
    • +``` +uv pip check [OPTIONS] +``` -
  • aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
    • +

    Options

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

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

    +

    By default, uv lists packages in the currently activated virtual environment, or a virtual environment (.venv) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.

    Supported formats:

    @@ -3648,7 +3648,7 @@ uv venv [OPTIONS] [NAME] ## uv cache -Manage the cache +Manage uv's cache

    Usage