diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 49c833954da3..7e5a7b5c3462 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -591,6 +591,19 @@ pub enum ProjectCommand { )] Remove(RemoveArgs), /// Update the project's environment (experimental). + /// + /// Syncing ensures that all project dependencies are installed and + /// up-to-date with the lockfile. Syncing also removes packages that are not + /// declared as dependencies of the project. + /// + /// If the project virtual environment (`.venv`) does not exist, it will be + /// created. + /// + /// The project is re-locked before syncing unless the `--locked` or + /// `--frozen` flag is provided. + /// + /// uv will search for a project in the current directory or any parent + /// directory. If a project cannot be found, uv will exit with an error. #[command( after_help = "Use `uv help sync` for more details.", after_long_help = "" @@ -2154,9 +2167,9 @@ pub struct RunArgs { /// /// Instead of checking if the lockfile is up-to-date, uses the versions in /// the lockfile as the source of truth. If the lockfile is missing, uv will - /// exit with an error. If the `pyproject.toml` includes new dependencies - /// that have not been included in the lockfile yet, they will not be - /// present in the environment. + /// exit with an error. If the `pyproject.toml` includes changes to + /// dependencies that have not been included in the lockfile yet, they will + /// not be present in the environment. #[arg(long, conflicts_with = "locked")] pub frozen: bool, @@ -2212,15 +2225,13 @@ pub struct RunArgs { #[derive(Args)] #[allow(clippy::struct_excessive_bools)] pub struct SyncArgs { - /// Include optional dependencies from the extra group name; may be provided more than once. + /// Include optional dependencies from the extra group name. /// - /// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources. + /// May be provided more than once. #[arg(long, conflicts_with = "all_extras", value_parser = extra_name_with_clap_error)] pub extra: Option>, /// Include all optional dependencies. - /// - /// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources. #[arg(long, conflicts_with = "extra")] pub all_extras: bool, @@ -2235,18 +2246,31 @@ pub struct SyncArgs { #[arg(long, overrides_with("dev"))] pub no_dev: bool, - /// When syncing, make the minimum necessary changes to satisfy the requirements. + /// Do not remove extraneous packages. + /// + /// When enabled, uv will make the minimum necessary changes to satisfy the + /// requirements. /// - /// By default, `uv sync` will remove any extraneous packages from the environment, unless - /// `--no-build-isolation` is enabled. + /// By default, syncing will remove any extraneous packages from the + /// environment, unless `--no-build-isolation` is enabled, in which case + /// extra packages are considered necessary for builds. #[arg(long)] pub no_clean: bool, /// Assert that the `uv.lock` will remain unchanged. + /// + /// Requires that the lockfile is up-to-date. If the lockfile is missing or + /// needs to be updated, uv will exit with an error. #[arg(long, conflicts_with = "frozen")] pub locked: bool, - /// Install without updating the `uv.lock` file. + /// Sync without updating the `uv.lock` file. + /// + /// Instead of checking if the lockfile is up-to-date, uses the versions in + /// the lockfile as the source of truth. If the lockfile is missing, uv will + /// exit with an error. If the `pyproject.toml` includes changes to dependencies + /// that have not been included in the lockfile yet, they will not be + /// present in the environment. #[arg(long, conflicts_with = "locked")] pub frozen: bool, @@ -2259,7 +2283,13 @@ pub struct SyncArgs { #[command(flatten)] pub refresh: RefreshArgs, - /// Sync a specific package in the workspace. + /// Sync for a specific package in the workspace. + /// + /// The workspace's environment (`.venv`) is updated to reflect the subset + /// of dependencies declared by the specified workspace member package. + /// + /// If not in a workspace, or if the workspace member does not exist, uv + /// will exit with an error. #[arg(long)] pub package: Option, @@ -2370,8 +2400,6 @@ pub struct AddArgs { pub raw_sources: bool, /// Commit to use when adding a dependency from Git. - /// - /// #[arg(long, group = "git-ref", action = clap::ArgAction::Set)] pub rev: Option, diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 1bee5247b118..284031ba05cd 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -124,7 +124,7 @@ uv run [OPTIONS]
--frozen

Run without updating the uv.lock file.

-

Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the pyproject.toml includes new dependencies that have not been included in the lockfile yet, they will not be present in the environment.

+

Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the pyproject.toml includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.

--help, -h

Display the concise help for this command

@@ -981,7 +981,15 @@ uv remove [OPTIONS] ... ## uv sync -Update the project's environment (experimental) +Update the project's environment (experimental). + +Syncing ensures that all project dependencies are installed and up-to-date with the lockfile. Syncing also removes packages that are not declared as dependencies of the project. + +If the project virtual environment (`.venv`) does not exist, it will be created. + +The project is re-locked before syncing unless the `--locked` or `--frozen` flag is provided. + +uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.

Usage

@@ -991,9 +999,7 @@ uv sync [OPTIONS]

Options

-
--all-extras

Include all optional dependencies.

- -

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

+
--all-extras

Include all optional dependencies

--cache-dir cache-dir

Path to the cache directory.

@@ -1027,9 +1033,9 @@ uv sync [OPTIONS]

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

-
--extra extra

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

+
--extra extra

Include optional dependencies from the extra group name.

-

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

+

May be provided more than once.

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

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

@@ -1043,7 +1049,9 @@ uv sync [OPTIONS]

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

-
--frozen

Install without updating the uv.lock file

+
--frozen

Sync without updating the uv.lock file.

+ +

Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the pyproject.toml includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.

--help, -h

Display the concise help for this command

@@ -1094,7 +1102,9 @@ uv sync [OPTIONS]
  • symlink: Symbolically link packages from the wheel into the site-packages directory
    • -
    --locked

    Assert that the uv.lock will remain unchanged

    +
    --locked

    Assert that the uv.lock will remain unchanged.

    + +

    Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.

    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    @@ -1124,9 +1134,11 @@ uv sync [OPTIONS]
    --no-cache, -n

    Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

    -
    --no-clean

    When syncing, make the minimum necessary changes to satisfy the requirements.

    +
    --no-clean

    Do not remove extraneous packages.

    + +

    When enabled, uv will make the minimum necessary changes to satisfy the requirements.

    -

    By default, uv sync will remove any extraneous packages from the environment, unless --no-build-isolation is enabled.

    +

    By default, syncing will remove any extraneous packages from the environment, unless --no-build-isolation is enabled, in which case extra packages are considered necessary for builds.

    --no-config

    Avoid discovering configuration files (pyproject.toml, uv.toml).

    @@ -1148,7 +1160,11 @@ uv sync [OPTIONS]

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

    -
    --package package

    Sync a specific package in the workspace

    +
    --package package

    Sync for a specific package in the workspace.

    + +

    The workspace’s environment (.venv) is updated to reflect the subset of dependencies declared by the specified workspace member package.

    + +

    If not in a workspace, or if the workspace member does not exist, uv will exit with an error.

    --prerelease prerelease

    The strategy to use when considering pre-release versions.