From 2abe56a357ddbddccbf910eda2845efba20b2dac Mon Sep 17 00:00:00 2001 From: Oshadha Gunawardena Date: Wed, 3 Dec 2025 23:45:36 +0530 Subject: [PATCH] Clarify `--project` flag help text to indicate project discovery (#16965) Clarify `--project` flag help text to indicate project discovery Update the help text for `--project` from "Run the command within the given project directory" to "Discover a project in the given directory" to better reflect its actual behavior. The `--project` flag affects file discovery (pyproject.toml, uv.toml, etc.) but does not change the working directory. Users should use `--directory` for changing the working directory. Fixes #16718 --- crates/uv-cli/src/lib.rs | 2 +- crates/uv/tests/it/help.rs | 18 +++---- docs/reference/cli.md | 98 +++++++++++++++++++------------------- 3 files changed, 59 insertions(+), 59 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index ba80820d8..e39d55056 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -345,7 +345,7 @@ pub struct GlobalArgs { #[arg(global = true, long, env = EnvVars::UV_WORKING_DIR)] pub directory: Option, - /// Run the command within the given project directory. + /// Discover a project in the given directory. /// /// All `pyproject.toml`, `uv.toml`, and `.python-version` files will be discovered by walking /// up the directory tree from the project root, as will the project's virtual environment diff --git a/crates/uv/tests/it/help.rs b/crates/uv/tests/it/help.rs index 7e665d0e7..b21578749 100644 --- a/crates/uv/tests/it/help.rs +++ b/crates/uv/tests/it/help.rs @@ -68,7 +68,7 @@ fn help() { --directory Change to the given directory prior to running the command [env: UV_WORKING_DIR=] --project - Run the command within the given project directory [env: UV_PROJECT=] + Discover a project in the given directory [env: UV_PROJECT=] --config-file The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=] --no-config @@ -149,7 +149,7 @@ fn help_flag() { --directory Change to the given directory prior to running the command [env: UV_WORKING_DIR=] --project - Run the command within the given project directory [env: UV_PROJECT=] + Discover a project in the given directory [env: UV_PROJECT=] --config-file The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=] --no-config @@ -229,7 +229,7 @@ fn help_short_flag() { --directory Change to the given directory prior to running the command [env: UV_WORKING_DIR=] --project - Run the command within the given project directory [env: UV_PROJECT=] + Discover a project in the given directory [env: UV_PROJECT=] --config-file The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=] --no-config @@ -419,7 +419,7 @@ fn help_subcommand() { [env: UV_WORKING_DIR=] --project - Run the command within the given project directory. + Discover a project in the given directory. All `pyproject.toml`, `uv.toml`, and `.python-version` files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment @@ -692,7 +692,7 @@ fn help_subsubcommand() { [env: UV_WORKING_DIR=] --project - Run the command within the given project directory. + Discover a project in the given directory. All `pyproject.toml`, `uv.toml`, and `.python-version` files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment @@ -783,7 +783,7 @@ fn help_flag_subcommand() { --directory Change to the given directory prior to running the command [env: UV_WORKING_DIR=] --project - Run the command within the given project directory [env: UV_PROJECT=] + Discover a project in the given directory [env: UV_PROJECT=] --config-file The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=] --no-config @@ -864,7 +864,7 @@ fn help_flag_subsubcommand() { --directory Change to the given directory prior to running the command [env: UV_WORKING_DIR=] --project - Run the command within the given project directory [env: UV_PROJECT=] + Discover a project in the given directory [env: UV_PROJECT=] --config-file The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=] --no-config @@ -1026,7 +1026,7 @@ fn help_with_global_option() { --directory Change to the given directory prior to running the command [env: UV_WORKING_DIR=] --project - Run the command within the given project directory [env: UV_PROJECT=] + Discover a project in the given directory [env: UV_PROJECT=] --config-file The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=] --no-config @@ -1149,7 +1149,7 @@ fn help_with_no_pager() { --directory Change to the given directory prior to running the command [env: UV_WORKING_DIR=] --project - Run the command within the given project directory [env: UV_PROJECT=] + Discover a project in the given directory [env: UV_PROJECT=] --config-file The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=] --no-config diff --git a/docs/reference/cli.md b/docs/reference/cli.md index d5a1b0fe0..151f9f867 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -112,7 +112,7 @@ uv auth login [OPTIONS]

When disabled, uv will only use locally cached data and locally available files.

May also be set with the UV_OFFLINE environment variable.

--password password

The password to use for the service.

Use - to read the password from stdin.

-
--project project

Run the command within the given project directory.

+
--project project

Discover a project in the given directory.

All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

@@ -185,7 +185,7 @@ uv auth logout [OPTIONS]

May also be set with the UV_NO_PROGRESS environment variable.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

-

May also be set with the UV_OFFLINE environment variable.

--project project

Run the command within the given project directory.

+

May also be set with the UV_OFFLINE environment variable.

--project project

Discover a project in the given directory.

All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

@@ -254,7 +254,7 @@ uv auth token [OPTIONS]

May also be set with the UV_NO_PROGRESS environment variable.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

-

May also be set with the UV_OFFLINE environment variable.

--project project

Run the command within the given project directory.

+

May also be set with the UV_OFFLINE environment variable.

--project project

Discover a project in the given directory.

All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

@@ -324,7 +324,7 @@ uv auth dir [OPTIONS] [SERVICE]

May also be set with the UV_NO_PROGRESS environment variable.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

-

May also be set with the UV_OFFLINE environment variable.

--project project

Run the command within the given project directory.

+

May also be set with the UV_OFFLINE environment variable.

--project project

Discover a project in the given directory.

All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

@@ -526,7 +526,7 @@ uv run [OPTIONS] [COMMAND]
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -722,7 +722,7 @@ uv init [OPTIONS] [PATH]

    Defines a [build-system] for the project.

    This is the default behavior when using --lib or --build-backend.

    When using --app, this will include a [project.scripts] entrypoint and use a src/ project structure.

    -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -933,7 +933,7 @@ uv add [OPTIONS] >
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -1123,7 +1123,7 @@ uv remove [OPTIONS] ...
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -1309,7 +1309,7 @@ uv version [OPTIONS] [VALUE]
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -1536,7 +1536,7 @@ uv sync [OPTIONS]
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -1755,7 +1755,7 @@ uv lock [OPTIONS]
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -1971,7 +1971,7 @@ uv export [OPTIONS]
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -2151,7 +2151,7 @@ uv tree [OPTIONS]
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -2300,7 +2300,7 @@ uv format [OPTIONS] [-- ...]
    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -2487,7 +2487,7 @@ uv tool run [OPTIONS] [COMMAND]
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -2718,7 +2718,7 @@ uv tool install [OPTIONS]
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -2936,7 +2936,7 @@ uv tool upgrade [OPTIONS] ...
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -3058,7 +3058,7 @@ uv tool list [OPTIONS]

    For example, spinners or progress bars.

    May also be set with the UV_NO_PROGRESS environment variable.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -3127,7 +3127,7 @@ uv tool uninstall [OPTIONS] ...

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -3191,7 +3191,7 @@ uv tool update-shell [OPTIONS]

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -3268,7 +3268,7 @@ from the following environment variables, in order of preference:

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -3419,7 +3419,7 @@ uv python list [OPTIONS] [REQUEST]
    • text: Plain text (for humans)
    • json: JSON (for computers)
      • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -3514,7 +3514,7 @@ uv python install [OPTIONS] [TARGETS]...

    This can also be set with UV_PYTHON_INSTALL_REGISTRY=0.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -3606,7 +3606,7 @@ uv python upgrade [OPTIONS] [TARGETS]...

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -3682,7 +3682,7 @@ uv python find [OPTIONS] [REQUEST]
    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -3765,7 +3765,7 @@ uv python pin [OPTIONS] [REQUEST]
    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -3843,7 +3843,7 @@ from the following environment variables, in order of preference:

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -3909,7 +3909,7 @@ uv python uninstall [OPTIONS] ...

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -3973,7 +3973,7 @@ uv python update-shell [OPTIONS]

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -4186,7 +4186,7 @@ uv pip compile [OPTIONS] >
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -4471,7 +4471,7 @@ uv pip sync [OPTIONS] ...
    --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.

    Unlike other install operations, this command does not require discovery of an existing Python environment and only searches for a Python interpreter to use for package resolution. If a suitable Python interpreter cannot be found, uv will install one. To disable this, add --no-python-downloads.

    -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -4774,7 +4774,7 @@ uv pip install [OPTIONS] |--editable 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -4991,7 +4991,7 @@ uv pip uninstall [OPTIONS] >
    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    May also be set with the UV_OFFLINE environment variable.

    --prefix prefix

    Uninstall packages from the specified --prefix directory

    -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -5063,7 +5063,7 @@ uv pip freeze [OPTIONS]

    When disabled, uv will only use locally cached data and locally available files.

    May also be set with the UV_OFFLINE environment variable.

    --path paths

    Restrict to the specified installation path for listing packages (can be used multiple times)

    --prefix prefix

    List packages from the specified --prefix directory

    -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -5175,7 +5175,7 @@ uv pip list [OPTIONS]

    May also be set with the UV_OFFLINE environment variable.

    --outdated

    List outdated packages.

    The latest version of each package will be shown alongside the installed version. Up-to-date packages will be omitted from the output.

    --prefix prefix

    List packages from the specified --prefix directory

    -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -5249,7 +5249,7 @@ uv pip show [OPTIONS] [PACKAGE]...
    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    May also be set with the UV_OFFLINE environment variable.

    --prefix prefix

    Show a package from the specified --prefix directory

    -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -5354,7 +5354,7 @@ uv pip tree [OPTIONS]

    When disabled, uv will only use locally cached data and locally available files.

    May also be set with the UV_OFFLINE environment variable.

    --outdated

    Show the latest available version of each package in the tree

    --package package

    Display only the specified packages

    -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -5423,7 +5423,7 @@ uv pip check [OPTIONS]

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -5611,7 +5611,7 @@ uv venv [OPTIONS] [PATH]
    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -5796,7 +5796,7 @@ uv build [OPTIONS] [SRC]
  • 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
    • -
    --project project

    Run the command within the given project directory.

    +
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -5914,7 +5914,7 @@ uv publish --publish-url https://upload.pypi.org/legacy/ --check-url https://pyp
    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    May also be set with the UV_OFFLINE environment variable.

    --password, -p password

    The password for the upload

    -

    May also be set with the UV_PUBLISH_PASSWORD environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_PUBLISH_PASSWORD environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -6011,7 +6011,7 @@ uv cache clean [OPTIONS] [PACKAGE]...

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -6074,7 +6074,7 @@ uv cache prune [OPTIONS]

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -6140,7 +6140,7 @@ uv cache dir [OPTIONS]

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -6201,7 +6201,7 @@ uv cache size [OPTIONS]

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -6281,7 +6281,7 @@ uv self update [OPTIONS] [TARGET_VERSION]

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -6340,7 +6340,7 @@ uv self version [OPTIONS]

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --output-format output-format
    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --output-format output-format
    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -6380,7 +6380,7 @@ uv generate-shell-completion [OPTIONS]

    By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.

    May also be set with the UV_MANAGED_PYTHON environment variable.

    --no-managed-python

    Disable use of uv-managed Python versions.

    Instead, uv will search for a suitable Python version on the system.

    -

    May also be set with the UV_NO_MANAGED_PYTHON environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_NO_MANAGED_PYTHON environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.

    @@ -6439,7 +6439,7 @@ uv help [OPTIONS] [COMMAND]...

    May also be set with the UV_NO_PROGRESS environment variable.

    --no-python-downloads

    Disable automatic downloads of Python.

    --offline

    Disable network access.

    When disabled, uv will only use locally cached data and locally available files.

    -

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Run the command within the given project directory.

    +

    May also be set with the UV_OFFLINE environment variable.

    --project project

    Discover a project in the given directory.

    All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

    Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

    See --directory to change the working directory entirely.