Python
/
uv
mirror of https://github.com/astral-sh/uv
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve `--python` CLI documentation (#5869) 

Closes #4400
This commit is contained in:
Zanie Blue 2024-08-07 11:37:10 -05:00 committed by GitHub
parent 32d8ea1698
commit 2df2092084
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 316 additions and 388 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
clippy.toml
View File

@ -1,6 +1,7 @@
doc-valid-idents = [ doc-valid-idents = [
"PyPI", "PyPI",
"PubGrub", "PubGrub",
"PyPy",
".." # Include the defaults ".." # Include the defaults
] ]

379
crates/uv-cli/src/lib.rs
View File

@ -244,7 +244,48 @@ pub enum Commands {
after_long_help = "" after_long_help = ""
)] )]
Tool(ToolNamespace), Tool(ToolNamespace),
/// Manage Python versions and installations (experimental).
/// Manage Python versions and installations (experimental)
///
/// Generally, uv first searches for Python in a virtual environment, either
/// active or in a `.venv` directory in the current working directory or
/// any parent directory. If a virtual environment is not required, uv will
/// then search for a Python interpreter. Python interpreters are found by
/// searching for Python executables in the `PATH` environment variable.
///
/// On Windows, the `py` launcher is also invoked to find Python
/// executables.
///
/// When preview is enabled, i.e., via `--preview` or by using a preview
/// command, uv will download Python if a version cannot be found. This
/// behavior can be disabled with the `--python-fetch` option.
///
/// The `--python` option allows requesting a different interpreter.
///
/// The following Python version request formats are supported:
///
/// - `<version>` e.g. `3`, `3.12`, `3.12.3`
/// - `<version-specifier>` e.g. `>=3.12,<3.13`
/// - `<implementation>` e.g. `cpython` or `cp`
/// - `<implementation>@<version>` e.g. `cpython@3.12`
/// - `<implementation><version>` e.g. `cpython3.12` or `cp312`
/// - `<implementation><version-specifier>` e.g. `cpython>=3.12,<3.13`
/// - `<implementation>-<version>-<os>-<arch>-<libc>` e.g.
/// `cpython-3.12.3-macos-aarch64-none`
///
/// Additionally, a specific system Python interpreter can often be
/// requested with:
///
/// - `<executable-path>` e.g. `/opt/homebrew/bin/python3`
/// - `<executable-name>` e.g. `mypython3`
/// - `<install-dir>` e.g. `/some/environment/`
///
/// When the `--python` option is used, normal discovery rules apply but
/// discovered interpreters are checked for compatibility with the request,
/// e.g., if `pypy` is requested, uv will first check if the virtual
/// environment contains a PyPy interpreter then check if each executable in
/// the path is a PyPy interpreter.
#[clap(verbatim_doc_comment)]
#[command( #[command(
after_help = "Use `uv help python` for more details.", after_help = "Use `uv help python` for more details.",
after_long_help = "" after_long_help = ""
@ -690,17 +731,16 @@ pub struct PipCompileArgs {
#[arg(long, env = "UV_CUSTOM_COMPILE_COMMAND")] #[arg(long, env = "UV_CUSTOM_COMPILE_COMMAND")]
pub custom_compile_command: Option<String>, pub custom_compile_command: Option<String>,
/// The Python interpreter against which to compile the requirements. /// The Python interpreter to use during resolution.
/// ///
/// By default, uv uses the virtual environment in the current working directory or any parent /// A Python interpreter is required for building source distributions to
/// directory, falling back to searching for a Python executable in `PATH`. The `--python` /// determine package metadata when there are not wheels.
/// option allows you to specify a different interpreter.
/// ///
/// Supported formats: /// The interpreter is also used to determine the default minimum Python
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// version, unless `--python-version` is provided.
/// `python3.10` on Linux and macOS. ///
/// - `python3.10` or `python.exe` looks for a binary with the given name in `PATH`. /// See `uv help python` for details on Python discovery and supported
/// - `/home/ferris/.local/bin/python3.10` uses the exact Python at the given path. /// request formats.
#[arg(long, verbatim_doc_comment, help_heading = "Python options")] #[arg(long, verbatim_doc_comment, help_heading = "Python options")]
pub python: Option<String>, pub python: Option<String>,
@ -781,11 +821,17 @@ pub struct PipCompileArgs {
#[arg(long, conflicts_with = "no_build")] #[arg(long, conflicts_with = "no_build")]
pub only_binary: Option<Vec<PackageNameSpecifier>>, pub only_binary: Option<Vec<PackageNameSpecifier>>,
/// The minimum Python version that should be supported by the resolved requirements (e.g., /// The Python version to use for resolution.
/// `3.8` or `3.8.17`).
/// ///
/// If a patch version is omitted, the minimum patch version is assumed. For example, `3.8` is /// For example, `3.8` or `3.8.17`.
/// mapped to `3.8.0`. ///
/// Defaults to the version of the Python interpreter used for resolution.
///
/// Defines the minimum Python version that must be supported by the
/// resolved requirements.
///
/// If a patch version is omitted, the minimum patch version is assumed. For
/// example, `3.8` is mapped to `3.8.0`.
#[arg(long, short, help_heading = "Python options")] #[arg(long, short, help_heading = "Python options")]
pub python_version: Option<PythonVersion>, pub python_version: Option<PythonVersion>,
@ -945,16 +991,13 @@ pub struct PipSyncArgs {
/// The Python interpreter into which packages should be installed. /// The Python interpreter into which packages should be installed.
/// ///
/// By default, uv installs into the virtual environment in the current working directory or /// By default, syncing requires a virtual environment. An path to an
/// any parent directory. The `--python` option allows you to specify a different interpreter, /// alternative Python can be provided, but it is only recommended in
/// which is intended for use in continuous integration (CI) environments or other automated /// continuous integration (CI) environments and should be used with
/// workflows. /// caution, as it can modify the system Python installation.
/// ///
/// Supported formats: /// See `uv help python` for details on Python discovery and supported
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// request formats.
/// `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.
#[arg( #[arg(
long, long,
short, short,
@ -1236,16 +1279,13 @@ pub struct PipInstallArgs {
/// The Python interpreter into which packages should be installed. /// The Python interpreter into which packages should be installed.
/// ///
/// By default, uv installs into the virtual environment in the current working directory or /// By default, installation requires a virtual environment. An path to an
/// any parent directory. The `--python` option allows you to specify a different interpreter, /// alternative Python can be provided, but it is only recommended in
/// which is intended for use in continuous integration (CI) environments or other automated /// continuous integration (CI) environments and should be used with
/// workflows. /// caution, as it can modify the system Python installation.
/// ///
/// Supported formats: /// See `uv help python` for details on Python discovery and supported
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// request formats.
/// `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.
#[arg( #[arg(
long, long,
short, short,
@ -1412,16 +1452,13 @@ pub struct PipUninstallArgs {
/// The Python interpreter from which packages should be uninstalled. /// The Python interpreter from which packages should be uninstalled.
/// ///
/// By default, uv uninstalls from the virtual environment in the current working directory or /// By default, uninstallation requires a virtual environment. An path to an
/// any parent directory. The `--python` option allows you to specify a different interpreter, /// alternative Python can be provided, but it is only recommended in
/// which is intended for use in continuous integration (CI) environments or other automated /// continuous integration (CI) environments and should be used with
/// workflows. /// caution, as it can modify the system Python installation.
/// ///
/// Supported formats: /// See `uv help python` for details on Python discovery and supported
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// request formats.
/// `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.
#[arg( #[arg(
long, long,
short, short,
@ -1505,15 +1542,12 @@ pub struct PipFreezeArgs {
/// The Python interpreter for which packages should be listed. /// The Python interpreter for which packages should be listed.
/// ///
/// By default, uv lists packages in the currently activated virtual environment, or a virtual /// By default, uv lists packages in a virtual environment but will show
/// environment (`.venv`) located in the current working directory or any parent directory, /// packages in a system Python environment if no virtual environment is
/// falling back to the system Python if no virtual environment is found. /// found.
/// ///
/// Supported formats: /// See `uv help python` for details on Python discovery and supported
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// request formats.
/// `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.
#[arg( #[arg(
long, long,
short, short,
@ -1523,15 +1557,11 @@ pub struct PipFreezeArgs {
)] )]
pub python: Option<String>, pub python: Option<String>,
/// List packages for the system Python. /// List packages in the system Python environment.
/// ///
/// By default, uv lists packages in the currently activated virtual environment, or a virtual /// Disables discovery of virtual environments.
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found. The `--system` option
/// instructs uv to use the first Python found in the system `PATH`.
/// ///
/// WARNING: `--system` is intended for use in continuous integration (CI) environments and /// See `uv help python` for details on Python discovery.
/// should be used with caution.
#[arg( #[arg(
long, long,
env = "UV_SYSTEM_PYTHON", env = "UV_SYSTEM_PYTHON",
@ -1576,15 +1606,12 @@ pub struct PipListArgs {
/// The Python interpreter for which packages should be listed. /// The Python interpreter for which packages should be listed.
/// ///
/// By default, uv lists packages in the currently activated virtual environment, or a virtual /// By default, uv lists packages in a virtual environment but will show
/// environment (`.venv`) located in the current working directory or any parent directory, /// packages in a system Python environment if no virtual environment is
/// falling back to the system Python if no virtual environment is found. /// found.
/// ///
/// Supported formats: /// See `uv help python` for details on Python discovery and supported
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// request formats.
/// `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.
#[arg( #[arg(
long, long,
short, short,
@ -1594,15 +1621,11 @@ pub struct PipListArgs {
)] )]
pub python: Option<String>, pub python: Option<String>,
/// List packages for the system Python. /// List packages in the system Python environment.
/// ///
/// By default, uv lists packages in the currently activated virtual environment, or a virtual /// Disables discovery of virtual environments.
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found. The `--system` option
/// instructs uv to use the first Python found in the system `PATH`.
/// ///
/// WARNING: `--system` is intended for use in continuous integration (CI) environments and /// See `uv help python` for details on Python discovery.
/// should be used with caution.
#[arg( #[arg(
long, long,
env = "UV_SYSTEM_PYTHON", env = "UV_SYSTEM_PYTHON",
@ -1621,17 +1644,14 @@ pub struct PipListArgs {
#[derive(Args)] #[derive(Args)]
#[allow(clippy::struct_excessive_bools)] #[allow(clippy::struct_excessive_bools)]
pub struct PipCheckArgs { pub struct PipCheckArgs {
/// The Python interpreter for which packages should be listed. /// The Python interpreter for which packages should be checked.
/// ///
/// By default, uv lists packages in the currently activated virtual environment, or a virtual /// By default, uv checks packages in a virtual environment but will check
/// environment (`.venv`) located in the current working directory or any parent directory, /// packages in a system Python environment if no virtual environment is
/// falling back to the system Python if no virtual environment is found. /// found.
/// ///
/// Supported formats: /// See `uv help python` for details on Python discovery and supported
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// request formats.
/// `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.
#[arg( #[arg(
long, long,
short, short,
@ -1641,15 +1661,11 @@ pub struct PipCheckArgs {
)] )]
pub python: Option<String>, pub python: Option<String>,
/// List packages for the system Python. /// Check packages in the system Python environment.
/// ///
/// By default, uv lists packages in the currently activated virtual environment, or a virtual /// Disables discovery of virtual environments.
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found. The `--system` option
/// instructs uv to use the first Python found in the system `PATH`.
/// ///
/// WARNING: `--system` is intended for use in continuous integration (CI) environments and /// See `uv help python` for details on Python discovery.
/// should be used with caution.
#[arg( #[arg(
long, long,
env = "UV_SYSTEM_PYTHON", env = "UV_SYSTEM_PYTHON",
@ -1676,17 +1692,14 @@ pub struct PipShowArgs {
#[arg(long, overrides_with("strict"), hide = true)] #[arg(long, overrides_with("strict"), hide = true)]
pub no_strict: bool, pub no_strict: bool,
/// The Python interpreter for which packages should be listed. /// The Python interpreter to find the package in.
/// ///
/// By default, uv lists packages in the currently activated virtual environment, or a virtual /// By default, uv looks for packages in a virtual environment but will look
/// environment (`.venv`) located in the current working directory or any parent directory, /// for packages in a system Python environment if no virtual environment is
/// falling back to the system Python if no virtual environment is found. /// found.
/// ///
/// Supported formats: /// See `uv help python` for details on Python discovery and supported
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// request formats.
/// `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.
#[arg( #[arg(
long, long,
short, short,
@ -1696,15 +1709,11 @@ pub struct PipShowArgs {
)] )]
pub python: Option<String>, pub python: Option<String>,
/// List packages for the system Python. /// Show a package in the system Python environment.
/// ///
/// By default, uv lists packages in the currently activated virtual environment, or a virtual /// Disables discovery of virtual environments.
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found. The `--system` option
/// instructs uv to use the first Python found in the system `PATH`.
/// ///
/// WARNING: `--system` is intended for use in continuous integration (CI) environments and /// See `uv help python` for details on Python discovery.
/// should be used with caution.
#[arg( #[arg(
long, long,
env = "UV_SYSTEM_PYTHON", env = "UV_SYSTEM_PYTHON",
@ -1740,15 +1749,12 @@ pub struct PipTreeArgs {
/// The Python interpreter for which packages should be listed. /// The Python interpreter for which packages should be listed.
/// ///
/// By default, uv lists packages in the currently activated virtual environment, or a virtual /// By default, uv lists packages in a virtual environment but will show
/// environment (`.venv`) located in the current working directory or any parent directory, /// packages in a system Python environment if no virtual environment is
/// falling back to the system Python if no virtual environment is found. /// found.
/// ///
/// Supported formats: /// See `uv help python` for details on Python discovery and supported
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// request formats.
/// `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.
#[arg( #[arg(
long, long,
short, short,
@ -1758,15 +1764,11 @@ pub struct PipTreeArgs {
)] )]
pub python: Option<String>, pub python: Option<String>,
/// List packages for the system Python. /// List packages in the system Python environment.
/// ///
/// By default, uv lists packages in the currently activated virtual environment, or a virtual /// Disables discovery of virtual environments.
/// environment (`.venv`) located in the current working directory or any parent directory,
/// falling back to the system Python if no virtual environment is found. The `--system` option
/// instructs uv to use the first Python found in the system `PATH`.
/// ///
/// WARNING: `--system` is intended for use in continuous integration (CI) environments and /// See `uv help python` for details on Python discovery.
/// should be used with caution.
#[arg( #[arg(
long, long,
env = "UV_SYSTEM_PYTHON", env = "UV_SYSTEM_PYTHON",
@ -1787,14 +1789,11 @@ pub struct PipTreeArgs {
pub struct VenvArgs { pub struct VenvArgs {
/// The Python interpreter to use for the virtual environment. /// The Python interpreter to use for the virtual environment.
/// ///
/// Supported formats: /// During virtual environment creation, uv will not look for Python
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// interpreters in virtual environments.
/// `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.
/// ///
/// Note that this is different from `--python-version` in `pip compile`, which takes `3.10` or `3.10.13` and /// See `uv python help` for details on Python discovery and supported
/// doesn't look for a Python interpreter on disk. /// request formats.
#[arg( #[arg(
long, long,
short, short,
@ -1804,14 +1803,7 @@ pub struct VenvArgs {
)] )]
pub python: Option<String>, pub python: Option<String>,
/// Use the system Python to uninstall packages. // TODO(zanieb): Hide me, I do nothing.
///
/// By default, uv uninstalls from the virtual environment in the current working directory or
/// any parent directory. The `--system` option instructs uv to use the first Python found in
/// the system `PATH`.
///
/// WARNING: `--system` is intended for use in continuous integration (CI) environments and
/// should be used with caution, as it can modify the system Python installation.
#[arg( #[arg(
long, long,
env = "UV_SYSTEM_PYTHON", env = "UV_SYSTEM_PYTHON",
@ -2199,17 +2191,17 @@ pub struct SyncArgs {
#[arg(long)] #[arg(long)]
pub package: Option<PackageName>, pub package: Option<PackageName>,
/// The Python interpreter to use to build the run environment. /// The Python interpreter to use for the project environment.
/// ///
/// By default, uv uses the virtual environment in the current working directory or any parent /// By default, the first interpreter that meets the project's
/// directory, falling back to searching for a Python executable in `PATH`. The `--python` /// `requires-python` constraint is used.
/// option allows you to specify a different interpreter.
/// ///
/// Supported formats: /// If a Python interpreter in a virtual environment is provided, the
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// packages will not be synced to the given environment. The interpreter
/// `python3.10` on Linux and macOS. /// will be used to create a virtual environment in the project.
/// - `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. /// See `uv help python` for details on Python discovery and supported
/// request formats.
#[arg( #[arg(
long, long,
short, short,
@ -2240,17 +2232,16 @@ pub struct LockArgs {
#[command(flatten)] #[command(flatten)]
pub refresh: RefreshArgs, pub refresh: RefreshArgs,
/// The Python interpreter to use to build the run environment. /// The Python interpreter to use during resolution.
/// ///
/// By default, uv uses the virtual environment in the current working directory or any parent /// A Python interpreter is required for building source distributions to
/// directory, falling back to searching for a Python executable in `PATH`. The `--python` /// determine package metadata when there are not wheels.
/// option allows you to specify a different interpreter.
/// ///
/// Supported formats: /// The interpreter is also used as the fallback value for the minimum
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// Python version if `requires-python` is not set.
/// `python3.10` on Linux and macOS. ///
/// - `python3.10` or `python.exe` looks for a binary with the given name in `PATH`. /// See `uv help python` for details on Python discovery and supported
/// - `/home/ferris/.local/bin/python3.10` uses the exact Python at the given path. /// request formats.
#[arg( #[arg(
long, long,
short, short,
@ -2334,18 +2325,10 @@ pub struct AddArgs {
#[arg(long, conflicts_with = "isolated")] #[arg(long, conflicts_with = "isolated")]
pub package: Option<PackageName>, pub package: Option<PackageName>,
/// The Python interpreter into which packages should be installed. /// The Python interpreter to use for resolving and syncing.
/// ///
/// By default, uv installs into the virtual environment in the current working directory or /// See `uv help python` for details on Python discovery and supported
/// any parent directory. The `--python` option allows you to specify a different interpreter, /// request formats.
/// 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.
#[arg( #[arg(
long, long,
short, short,
@ -2392,18 +2375,10 @@ pub struct RemoveArgs {
#[arg(long, conflicts_with = "isolated")] #[arg(long, conflicts_with = "isolated")]
pub package: Option<PackageName>, pub package: Option<PackageName>,
/// The Python interpreter into which packages should be installed. /// The Python interpreter to use for resolving and syncing.
/// ///
/// By default, uv installs into the virtual environment in the current working directory or /// See `uv help python` for details on Python discovery and supported
/// any parent directory. The `--python` option allows you to specify a different interpreter, /// request formats.
/// 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.
#[arg( #[arg(
long, long,
short, short,
@ -2454,18 +2429,13 @@ pub struct TreeArgs {
#[arg(long, conflicts_with = "universal")] #[arg(long, conflicts_with = "universal")]
pub python_platform: Option<TargetTriple>, pub python_platform: Option<TargetTriple>,
/// The Python interpreter for which packages should be listed. /// The Python interpreter to use for resolution.
/// ///
/// By default, uv installs into the virtual environment in the current working directory or /// A Python interpreter is required to perform the lock before displaying
/// any parent directory. The `--python` option allows you to specify a different interpreter, /// the tree.
/// which is intended for use in continuous integration (CI) environments or other automated
/// workflows.
/// ///
/// Supported formats: /// See `uv help python` for details on Python discovery and supported
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or /// request formats.
/// `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.
#[arg( #[arg(
long, long,
short, short,
@ -2552,15 +2522,8 @@ pub struct ToolRunArgs {
/// The Python interpreter to use to build the run environment. /// 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 /// See `uv help python` for details on Python discovery and supported
/// directory, falling back to searching for a Python executable in `PATH`. The `--python` /// request formats.
/// 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.
#[arg( #[arg(
long, long,
short, short,
@ -2617,15 +2580,8 @@ pub struct ToolInstallArgs {
/// The Python interpreter to use to build the tool environment. /// The Python interpreter to use to build the tool environment.
/// ///
/// By default, uv will search for a Python executable in the `PATH`. uv ignores virtual /// See `uv help python` for details on Python discovery and supported
/// environments while looking for interpreter for tools. The `--python` option allows /// request formats.
/// 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.
#[arg( #[arg(
long, long,
short, short,
@ -2716,9 +2672,12 @@ pub struct PythonListArgs {
pub struct PythonInstallArgs { pub struct PythonInstallArgs {
/// The Python version(s) to install. /// The Python version(s) to install.
/// ///
/// If not provided, the requested Python version(s) will be read from the `.python-versions` /// If not provided, the requested Python version(s) will be read from the
/// or `.python-version` files. If neither file is present, uv will check if it has /// `.python-versions` or `.python-version` files. If neither file is
/// installed any Python versions. If not, it will install the latest stable version of Python. /// present, uv will check if it has installed any Python versions. If not,
/// it will install the latest stable version of Python.
///
/// See `uv help python` to view supported request formats.
pub targets: Vec<String>, pub targets: Vec<String>,
/// Reinstall the requested Python version, if it's already installed. /// Reinstall the requested Python version, if it's already installed.
@ -2730,6 +2689,8 @@ pub struct PythonInstallArgs {
#[allow(clippy::struct_excessive_bools)] #[allow(clippy::struct_excessive_bools)]
pub struct PythonUninstallArgs { pub struct PythonUninstallArgs {
/// The Python version(s) to uninstall. /// The Python version(s) to uninstall.
///
/// See `uv help python` to view supported request formats.
#[arg(required = true)] #[arg(required = true)]
pub targets: Vec<String>, pub targets: Vec<String>,
@ -2742,13 +2703,21 @@ pub struct PythonUninstallArgs {
#[allow(clippy::struct_excessive_bools)] #[allow(clippy::struct_excessive_bools)]
pub struct PythonFindArgs { pub struct PythonFindArgs {
/// The Python request. /// The Python request.
///
/// See `uv help python` to view supported request formats.
pub request: Option<String>, pub request: Option<String>,
} }
#[derive(Args)] #[derive(Args)]
#[allow(clippy::struct_excessive_bools)] #[allow(clippy::struct_excessive_bools)]
pub struct PythonPinArgs { pub struct PythonPinArgs {
/// The Python version. /// The Python version request.
///
/// uv supports more formats than other tools that read `.python-version`
/// files, i.e., `pyenv`. If compatibility with those tools is needed, only
/// use version numbers instead of complex requests such as `cpython@3.10`.
///
/// See `uv help python` to view supported request formats.
pub request: Option<String>, pub request: Option<String>,
/// Write the resolved Python interpreter path instead of the request. /// Write the resolved Python interpreter path instead of the request.

41
crates/uv/tests/help.rs
View File

@ -201,6 +201,45 @@ fn help_subcommand() {
----- stdout ----- ----- stdout -----
Manage Python versions and installations (experimental) Manage Python versions and installations (experimental)
Generally, uv first searches for Python in a virtual environment, either
active or in a `.venv` directory in the current working directory or
any parent directory. If a virtual environment is not required, uv will
then search for a Python interpreter. Python interpreters are found by
searching for Python executables in the `PATH` environment variable.
On Windows, the `py` launcher is also invoked to find Python
executables.
When preview is enabled, i.e., via `--preview` or by using a preview
command, uv will download Python if a version cannot be found. This
behavior can be disabled with the `--python-fetch` option.
The `--python` option allows requesting a different interpreter.
The following Python version request formats are supported:
- `<version>` e.g. `3`, `3.12`, `3.12.3`
- `<version-specifier>` e.g. `>=3.12,<3.13`
- `<implementation>` e.g. `cpython` or `cp`
- `<implementation>@<version>` e.g. `cpython@3.12`
- `<implementation><version>` e.g. `cpython3.12` or `cp312`
- `<implementation><version-specifier>` e.g. `cpython>=3.12,<3.13`
- `<implementation>-<version>-<os>-<arch>-<libc>` e.g.
`cpython-3.12.3-macos-aarch64-none`
Additionally, a specific system Python interpreter can often be
requested with:
- `<executable-path>` e.g. `/opt/homebrew/bin/python3`
- `<executable-name>` e.g. `mypython3`
- `<install-dir>` e.g. `/some/environment/`
When the `--python` option is used, normal discovery rules apply but
discovered interpreters are checked for compatibility with the request,
e.g., if `pypy` is requested, uv will first check if the virtual
environment contains a PyPy interpreter then check if each executable in
the path is a PyPy interpreter.
Usage: uv python [OPTIONS] <COMMAND> Usage: uv python [OPTIONS] <COMMAND>
Commands: Commands:
@ -343,6 +382,8 @@ fn help_subsubcommand() {
or `.python-version` files. If neither file is present, uv will check if it has installed or `.python-version` files. If neither file is present, uv will check if it has installed
any Python versions. If not, it will install the latest stable version of Python. any Python versions. If not, it will install the latest stable version of Python.
See `uv help python` to view supported request formats.
Options: Options:
-r, --reinstall -r, --reinstall
Reinstall the requested Python version, if it's already installed Reinstall the requested Python version, if it's already installed

283
docs/reference/cli.md
View File

@ -462,19 +462,9 @@ uv add [OPTIONS] <REQUIREMENTS>...
</dd><dt><code>--package</code> <i>package</i></dt><dd><p>Add the dependency to a specific package in the workspace</p> </dd><dt><code>--package</code> <i>package</i></dt><dd><p>Add the dependency to a specific package in the workspace</p>
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter into which packages should be installed.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use for resolving and syncing.</p>
<p>By default, uv installs into the virtual environment in the current working directory or any parent directory. The <code>--python</code> option allows you to specify a different interpreter, which is intended for use in continuous integration (CI) environments or other automated workflows.</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<p>Supported formats:</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -649,19 +639,9 @@ uv remove [OPTIONS] <REQUIREMENTS>...
</dd><dt><code>--package</code> <i>package</i></dt><dd><p>Remove the dependency from a specific package in the workspace</p> </dd><dt><code>--package</code> <i>package</i></dt><dd><p>Remove the dependency from a specific package in the workspace</p>
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter into which packages should be installed.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use for resolving and syncing.</p>
<p>By default, uv installs into the virtual environment in the current working directory or any parent directory. The <code>--python</code> option allows you to specify a different interpreter, which is intended for use in continuous integration (CI) environments or other automated workflows.</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<p>Supported formats:</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -832,19 +812,13 @@ uv sync [OPTIONS]
</dd><dt><code>--package</code> <i>package</i></dt><dd><p>Sync a specific package in the workspace</p> </dd><dt><code>--package</code> <i>package</i></dt><dd><p>Sync a specific package in the workspace</p>
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to build the run environment.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use for the project environment.</p>
<p>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 <code>PATH</code>. The <code>--python</code> option allows you to specify a different interpreter.</p> <p>By default, the first interpreter that meets the project&#8217;s <code>requires-python</code> constraint is used.</p>
<p>Supported formats:</p> <p>If a Python interpreter in a virtual environment is provided, the packages will not be synced to the given environment. The interpreter will be used to create a virtual environment in the project.</p>
<ul> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -1009,19 +983,13 @@ uv lock [OPTIONS]
</dd><dt><code>--refresh-package</code> <i>refresh-package</i></dt><dd><p>Refresh cached data for a specific package</p> </dd><dt><code>--refresh-package</code> <i>refresh-package</i></dt><dd><p>Refresh cached data for a specific package</p>
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to build the run environment.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use during resolution.</p>
<p>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 <code>PATH</code>. The <code>--python</code> option allows you to specify a different interpreter.</p> <p>A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.</p>
<p>Supported formats:</p> <p>The interpreter is also used as the fallback value for the minimum Python version if <code>requires-python</code> is not set.</p>
<ul> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -1232,19 +1200,11 @@ uv tree [OPTIONS]
<li><code>aarch64-manylinux_2_31</code>: An ARM64 target for the <code>manylinux_2_31</code> platform</li> <li><code>aarch64-manylinux_2_31</code>: An ARM64 target for the <code>manylinux_2_31</code> platform</li>
</ul> </ul>
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter for which packages should be listed.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use for resolution.</p>
<p>By default, uv installs into the virtual environment in the current working directory or any parent directory. The <code>--python</code> option allows you to specify a different interpreter, which is intended for use in continuous integration (CI) environments or other automated workflows.</p> <p>A Python interpreter is required to perform the lock before displaying the tree.</p>
<p>Supported formats:</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -1445,17 +1405,7 @@ uv tool run [OPTIONS] [COMMAND]
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to build the run environment.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to build the run environment.</p>
<p>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 <code>PATH</code>. The <code>--python</code> option allows you to specify a different interpreter.</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<p>Supported formats:</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -1632,17 +1582,7 @@ uv tool install [OPTIONS] <PACKAGE>
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to build the tool environment.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to build the tool environment.</p>
<p>By default, uv will search for a Python executable in the <code>PATH</code>. uv ignores virtual environments while looking for interpreter for tools. The <code>--python</code> option allows you to specify a different interpreter.</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<p>Supported formats:</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -1932,6 +1872,45 @@ uv tool dir [OPTIONS]
Manage Python versions and installations (experimental) Manage Python versions and installations (experimental)
Generally, uv first searches for Python in a virtual environment, either
active or in a `.venv` directory in the current working directory or
any parent directory. If a virtual environment is not required, uv will
then search for a Python interpreter. Python interpreters are found by
searching for Python executables in the `PATH` environment variable.
On Windows, the `py` launcher is also invoked to find Python
executables.
When preview is enabled, i.e., via `--preview` or by using a preview
command, uv will download Python if a version cannot be found. This
behavior can be disabled with the `--python-fetch` option.
The `--python` option allows requesting a different interpreter.
The following Python version request formats are supported:
- `<version>` e.g. `3`, `3.12`, `3.12.3`
- `<version-specifier>` e.g. `>=3.12,<3.13`
- `<implementation>` e.g. `cpython` or `cp`
- `<implementation>@<version>` e.g. `cpython@3.12`
- `<implementation><version>` e.g. `cpython3.12` or `cp312`
- `<implementation><version-specifier>` e.g. `cpython>=3.12,<3.13`
- `<implementation>-<version>-<os>-<arch>-<libc>` e.g.
`cpython-3.12.3-macos-aarch64-none`
Additionally, a specific system Python interpreter can often be
requested with:
- `<executable-path>` e.g. `/opt/homebrew/bin/python3`
- `<executable-name>` e.g. `mypython3`
- `<install-dir>` e.g. `/some/environment/`
When the `--python` option is used, normal discovery rules apply but
discovered interpreters are checked for compatibility with the request,
e.g., if `pypy` is requested, uv will first check if the virtual
environment contains a PyPy interpreter then check if each executable in
the path is a PyPy interpreter.
<h3 class="cli-reference">Usage</h3> <h3 class="cli-reference">Usage</h3>
``` ```
@ -2028,6 +2007,8 @@ uv python install [OPTIONS] [TARGETS]...
<p>If not provided, the requested Python version(s) will be read from the <code>.python-versions</code> or <code>.python-version</code> files. If neither file is present, uv will check if it has installed any Python versions. If not, it will install the latest stable version of Python.</p> <p>If not provided, the requested Python version(s) will be read from the <code>.python-versions</code> or <code>.python-version</code> files. If neither file is present, uv will check if it has installed any Python versions. If not, it will install the latest stable version of Python.</p>
<p>See <code>uv help python</code> to view supported request formats.</p>
</dd></dl> </dd></dl>
<h3 class="cli-reference">Options</h3> <h3 class="cli-reference">Options</h3>
@ -2090,7 +2071,9 @@ uv python find [OPTIONS] [REQUEST]
<h3 class="cli-reference">Arguments</h3> <h3 class="cli-reference">Arguments</h3>
<dl class="cli-reference"><dt><code>REQUEST</code></dt><dd><p>The Python request</p> <dl class="cli-reference"><dt><code>REQUEST</code></dt><dd><p>The Python request.</p>
<p>See <code>uv help python</code> to view supported request formats.</p>
</dd></dl> </dd></dl>
@ -2154,7 +2137,11 @@ uv python pin [OPTIONS] [REQUEST]
<h3 class="cli-reference">Arguments</h3> <h3 class="cli-reference">Arguments</h3>
<dl class="cli-reference"><dt><code>REQUEST</code></dt><dd><p>The Python version</p> <dl class="cli-reference"><dt><code>REQUEST</code></dt><dd><p>The Python version request.</p>
<p>uv supports more formats than other tools that read <code>.python-version</code> files, i.e., <code>pyenv</code>. If compatibility with those tools is needed, only use version numbers instead of complex requests such as <code>cpython@3.10</code>.</p>
<p>See <code>uv help python</code> to view supported request formats.</p>
</dd></dl> </dd></dl>
@ -2276,7 +2263,9 @@ uv python uninstall [OPTIONS] <TARGETS>...
<h3 class="cli-reference">Arguments</h3> <h3 class="cli-reference">Arguments</h3>
<dl class="cli-reference"><dt><code>TARGETS</code></dt><dd><p>The Python version(s) to uninstall</p> <dl class="cli-reference"><dt><code>TARGETS</code></dt><dd><p>The Python version(s) to uninstall.</p>
<p>See <code>uv help python</code> to view supported request formats.</p>
</dd></dl> </dd></dl>
@ -2522,19 +2511,13 @@ uv pip compile [OPTIONS] <SRC_FILE>...
<p>Used to reflect custom build scripts and commands that wrap <code>uv pip compile</code>.</p> <p>Used to reflect custom build scripts and commands that wrap <code>uv pip compile</code>.</p>
</dd><dt><code>--python</code> <i>python</i></dt><dd><p>The Python interpreter against which to compile the requirements.</p> </dd><dt><code>--python</code> <i>python</i></dt><dd><p>The Python interpreter to use during resolution.</p>
<p>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 <code>PATH</code>. The <code>--python</code> option allows you to specify a different interpreter.</p> <p>A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.</p>
<p>Supported formats:</p> <p>The interpreter is also used to determine the default minimum Python version, unless <code>--python-version</code> is provided.</p>
<ul> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--no-binary</code> <i>no-binary</i></dt><dd><p>Don&#8217;t install pre-built wheels.</p> </dd><dt><code>--no-binary</code> <i>no-binary</i></dt><dd><p>Don&#8217;t install pre-built wheels.</p>
@ -2548,7 +2531,13 @@ uv pip compile [OPTIONS] <SRC_FILE>...
<p>Multiple packages may be provided. Disable binaries for all packages with <code>:all:</code>. Clear previously specified packages with <code>:none:</code>.</p> <p>Multiple packages may be provided. Disable binaries for all packages with <code>:all:</code>. Clear previously specified packages with <code>:none:</code>.</p>
</dd><dt><code>--python-version</code>, <code>-p</code> <i>python-version</i></dt><dd><p>The minimum Python version that should be supported by the resolved requirements (e.g., <code>3.8</code> or <code>3.8.17</code>).</p> </dd><dt><code>--python-version</code>, <code>-p</code> <i>python-version</i></dt><dd><p>The Python version to use for resolution.</p>
<p>For example, <code>3.8</code> or <code>3.8.17</code>.</p>
<p>Defaults to the version of the Python interpreter used for resolution.</p>
<p>Defines the minimum Python version that must be supported by the resolved requirements.</p>
<p>If a patch version is omitted, the minimum patch version is assumed. For example, <code>3.8</code> is mapped to <code>3.8.0</code>.</p> <p>If a patch version is omitted, the minimum patch version is assumed. For example, <code>3.8</code> is mapped to <code>3.8.0</code>.</p>
@ -2742,17 +2731,9 @@ uv pip sync [OPTIONS] <SRC_FILE>...
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter into which packages should be installed.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter into which packages should be installed.</p>
<p>By default, uv installs into the virtual environment in the current working directory or any parent directory. The <code>--python</code> option allows you to specify a different interpreter, which is intended for use in continuous integration (CI) environments or other automated workflows.</p> <p>By default, syncing requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.</p>
<p>Supported formats:</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--target</code> <i>target</i></dt><dd><p>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</p> </dd><dt><code>--target</code> <i>target</i></dt><dd><p>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</p>
@ -3012,17 +2993,9 @@ uv pip install [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>|--editable <EDITAB
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter into which packages should be installed.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter into which packages should be installed.</p>
<p>By default, uv installs into the virtual environment in the current working directory or any parent directory. The <code>--python</code> option allows you to specify a different interpreter, which is intended for use in continuous integration (CI) environments or other automated workflows.</p> <p>By default, installation requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.</p>
<p>Supported formats:</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--target</code> <i>target</i></dt><dd><p>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</p> </dd><dt><code>--target</code> <i>target</i></dt><dd><p>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</p>
@ -3155,17 +3128,9 @@ uv pip uninstall [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>>
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter from which packages should be uninstalled.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter from which packages should be uninstalled.</p>
<p>By default, uv uninstalls from the virtual environment in the current working directory or any parent directory. The <code>--python</code> option allows you to specify a different interpreter, which is intended for use in continuous integration (CI) environments or other automated workflows.</p> <p>By default, uninstallation requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.</p>
<p>Supported formats:</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--keyring-provider</code> <i>keyring-provider</i></dt><dd><p>Attempt to use <code>keyring</code> for authentication for remote requirements files.</p> </dd><dt><code>--keyring-provider</code> <i>keyring-provider</i></dt><dd><p>Attempt to use <code>keyring</code> for authentication for remote requirements files.</p>
@ -3244,17 +3209,9 @@ uv pip freeze [OPTIONS]
<dl class="cli-reference"><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter for which packages should be listed.</p> <dl class="cli-reference"><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter for which packages should be listed.</p>
<p>By default, uv lists packages in the currently activated virtual environment, or a virtual environment (<code>.venv</code>) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.</p> <p>By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.</p>
<p>Supported formats:</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -3330,17 +3287,9 @@ uv pip list [OPTIONS]
</ul> </ul>
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter for which packages should be listed.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter for which packages should be listed.</p>
<p>By default, uv lists packages in the currently activated virtual environment, or a virtual environment (<code>.venv</code>) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.</p> <p>By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.</p>
<p>Supported formats:</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -3406,19 +3355,11 @@ uv pip show [OPTIONS] [PACKAGE]...
<h3 class="cli-reference">Options</h3> <h3 class="cli-reference">Options</h3>
<dl class="cli-reference"><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter for which packages should be listed.</p> <dl class="cli-reference"><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to find the package in.</p>
<p>By default, uv lists packages in the currently activated virtual environment, or a virtual environment (<code>.venv</code>) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.</p> <p>By default, uv looks for packages in a virtual environment but will look for packages in a system Python environment if no virtual environment is found.</p>
<p>Supported formats:</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -3487,17 +3428,9 @@ uv pip tree [OPTIONS]
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter for which packages should be listed.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter for which packages should be listed.</p>
<p>By default, uv lists packages in the currently activated virtual environment, or a virtual environment (<code>.venv</code>) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.</p> <p>By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.</p>
<p>Supported formats:</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -3557,19 +3490,11 @@ uv pip check [OPTIONS]
<h3 class="cli-reference">Options</h3> <h3 class="cli-reference">Options</h3>
<dl class="cli-reference"><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter for which packages should be listed.</p> <dl class="cli-reference"><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter for which packages should be checked.</p>
<p>By default, uv lists packages in the currently activated virtual environment, or a virtual environment (<code>.venv</code>) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.</p> <p>By default, uv checks packages in a virtual environment but will check packages in a system Python environment if no virtual environment is found.</p>
<p>Supported formats:</p> <p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p>
<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -3637,17 +3562,9 @@ uv venv [OPTIONS] [NAME]
<dl class="cli-reference"><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use for the virtual environment.</p> <dl class="cli-reference"><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use for the virtual environment.</p>
<p>Supported formats:</p> <p>During virtual environment creation, uv will not look for Python interpreters in virtual environments.</p>
<ul> <p>See <code>uv python help</code> for details on Python discovery and supported request formats.</p>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
<p>Note that this is different from <code>--python-version</code> in <code>pip compile</code>, which takes <code>3.10</code> or <code>3.10.13</code> and doesn&#8217;t look for a Python interpreter on disk.</p>
</dd><dt><code>--prompt</code> <i>prompt</i></dt><dd><p>Provide an alternative prompt prefix for the virtual environment.</p> </dd><dt><code>--prompt</code> <i>prompt</i></dt><dd><p>Provide an alternative prompt prefix for the virtual environment.</p>