diff --git a/docs/concepts/projects/sync.md b/docs/concepts/projects/sync.md index 46c66696c6bf..357c108e582b 100644 --- a/docs/concepts/projects/sync.md +++ b/docs/concepts/projects/sync.md @@ -1,33 +1,46 @@ # Locking and syncing -### Creating the lockfile +Locking is the process of resolving your project's dependencies into a +[lockfile](./layout.md#the-lockfile). Syncing is the process of installing a subset of packages from +the lockfile into the [project environment](./layout.md#the-project-environment). -The lockfile is created and updated during uv invocations that use the project environment, i.e., -`uv sync` and `uv run`. The lockfile may also be explicitly created or updated using `uv lock`: +## Automatic lock and sync + +Locking and syncing are _automatic_ in uv. For example, when `uv run` is used, the project is locked +and synced before invoking the requested command. This ensures the project environment is always +up-to-date. Similarly, commands which read the lockfile, such as `uv tree`, will automatically +update it before running. + +To disable automatic locking, use the `--locked` option: ```console -$ uv lock +$ uv run --locked ... ``` -### Exporting the lockfile +If the lockfile is not up-to-date, an error will be raised instead of updating the lockfile. -If you need to integrate uv with other tools or workflows, you can export `uv.lock` to -`requirements.txt` format with `uv export --format requirements-txt`. The generated -`requirements.txt` file can then be installed via `uv pip install`, or with other tools like `pip`. +To use the lockfile without checking if it is up-to-date, use the `--frozen` option: -In general, we recommend against using both a `uv.lock` and a `requirements.txt` file. If you find -yourself exporting a `uv.lock` file, consider opening an issue to discuss your use case. +```console +$ uv run --frozen ... +``` -### Checking if the lockfile is up-to-date +Similarly, to run a command without checking if the environment is up to date, use the `--no-sync` +option: -To avoid updating the lockfile during `uv sync` and `uv run` invocations, use the `--frozen` flag. +```console +$ uv run --no-sync ... +``` -To avoid updating the environment during `uv run` invocations, use the `--no-sync` flag. +## Checking if the lockfile is up-to-date -To assert the lockfile matches the project metadata, use the `--locked` flag. If the lockfile is not -up-to-date, an error will be raised instead of updating the lockfile. +When considering if the lockfile is up-to-date, uv will check if it matches the project metadata. +For example, if add a dependency to your `pyproject.toml`, the `uv.lock` will be outdated. -You can also check if the lockfile is up-to-date by passing the `--check` flag to `uv lock`: +uv will not consider lockfiles outdated when new versions of packages are released — the lockfile +needs to be explicitly updated to + +You can check if the lockfile is up-to-date by passing the `--check` flag to `uv lock`: ```console $ uv lock --check @@ -35,10 +48,101 @@ $ uv lock --check This is equivalent to the `--locked` flag for other commands. -### Upgrading locked package versions +## Creating the lockfile + +While the lockfile is created [automatically](#automatic-lock-and-sync), the lockfile may also be +explicitly created or updated using `uv lock`: + +```console +$ uv lock +``` + +## Syncing the environment + +While the environment is synced [automatically](#automatic-lock-and-sync), it may also be explicitly +synced using `uv sync`: + +```console +$ uv sync +``` + +Syncing the environment manually is especially useful for ensuring your editor has the correct +versions of dependencies. + +### Editable installation + +When the environment is synced, uv will install the project (and other workspace members) as +_editable_ packages. This means a re-sync is not necessary for changes to be reflected in the +environment. + +To opt-out of this behavior, use the `--no-editable` option. + +!!! note + + If the project is not define a build system, it will not be installed. + See the documentation about [Build systems](./config.md#build-systems) for details. + +### Retaining extraneous packages + +Syncing is "exact" by default, which means it will remove any packages that are not present in the +lockfile. + +To retain extraneous packages, use the `--inexact` option: + +```console +$ uv sync --inexact +``` -By default, uv will prefer the locked versions of packages when running `uv sync` and `uv lock` with -an existing `uv.lock` file. Package versions will only change if the project's dependency +### Syncing optional dependencies + +uv reads optional dependencies from the `[project.optional-dependencies]` table. These are +frequently referred to as "extras". + +uv does not sync extras by default. Use the `--extra` option to include an extra. + +```console +$ uv sync --extra foo +``` + +To quickly enable all extras, use the `--all-extras` option. + +See the [Optional dependencies](./dependencies.md#optional-dependencies) documentation for details +on how to manage optional dependencies. + +### Syncing development dependencies + +uv reads development dependencies from the `[dependency-groups]` table (as defined in +[PEP 735](https://peps.python.org/pep-0735/)). + +The `dev` group is special-cased and synced by default. See the +[Default groups](./dependencies.md#default-groups) documentation for details on changing the +defaults. + +The `--no-dev` flag can be used to exclude the `dev` group. + +The `--only-dev` flag can be used to install the `dev` group _without_ the project and its +dependencies. + +Additional groups can be included or excluded with the `--all-groups`, `--no-default-groups`, +`--group `, `--only-group `, and `--no-group ` options. The semantics of +`--only-group` are the same as `--only-dev`, the project will not be included. However, +`--only-group` will also exclude default groups. + +Group exclusions always take precedence over inclusions, so given the command: + +``` +$ uv sync --no-group foo --group foo +``` + +The `foo` group would not be installed. + +See the [Development dependencies](./dependencies.md#development-dependencies) documentation for +details on how to manage development dependencies. + +## Upgrading locked package versions + +With an existing `uv.lock` file, uv will prefer the previously locked versions of packages when +running `uv sync` and `uv lock`. Package versions will only change if the project's dependency constraints exclude the previous, locked version. To upgrade all packages: @@ -69,3 +173,30 @@ project defines an upper bound for a package then an upgrade will not go beyond the `main` branch, uv will prefer the locked commit SHA in an existing `uv.lock` file over the latest commit on the `main` branch, unless the `--upgrade` or `--upgrade-package` flags are used. + +These flags can also be provided to `uv sync` or `uv run` to update the lockfile _and_ the +environment. + +## Exporting the lockfile + +If you need to integrate uv with other tools or workflows, you can export `uv.lock` to +`requirements.txt` format with `uv export --format requirements-txt`. The generated +`requirements.txt` file can then be installed via `uv pip install`, or with other tools like `pip`. + +In general, we recommend against using both a `uv.lock` and a `requirements.txt` file. If you find +yourself exporting a `uv.lock` file, consider opening an issue to discuss your use case. + +## Partial installations + +Sometimes it's helpful to perform installations in multiple steps, e.g., for optimal layer caching +while building a Docker image. `uv sync` has several flags for this purpose. + +- `--no-install-project`: Do not install the current project +- `--no-install-workspace`: Do not install any workspace members, including the root project +- `--no-install-package `: Do not install the given package(s) + +When these options are used, all of the dependencies of the target are still installed. For example, +`--no-install-project` will omit the _project_ but not any of its dependencies. + +If used improperly, these flags can result in a broken environment since a package can be missing +its dependencies.