diff --git a/docs/concepts/projects/layout.md b/docs/concepts/projects/layout.md index 1bf39b1e3..caa7fbf58 100644 --- a/docs/concepts/projects/layout.md +++ b/docs/concepts/projects/layout.md @@ -41,7 +41,7 @@ be activated as normal for a virtual environment. When `uv run` is invoked, it will create the project environment if it does not exist yet or ensure it is up-to-date if it exists. The project environment can also be explicitly created with -`uv sync`. +`uv sync`. See the [locking and syncing](./sync.md) documentation for details. It is _not_ recommended to modify the project environment manually, e.g., with `uv pip install`. For project dependencies, use `uv add` to add a package to the environment. For one-off requirements, @@ -75,8 +75,9 @@ A lockfile ensures that developers working on the project are using a consistent versions. Additionally, it ensures when deploying the project as an application that the exact set of used package versions is known. -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 updated using `uv lock`. +The lockfile is [automatically created and updated](./sync.md#automatic-lock-and-sync) during uv +invocations that use the project environment, i.e., `uv sync` and `uv run`. The lockfile may also be +explicitly updated using `uv lock`. `uv.lock` is a human-readable TOML file but is managed by uv and should not be edited manually. There is no Python standard for lockfiles at this time, so the format of this file is specific to uv diff --git a/docs/concepts/projects/sync.md b/docs/concepts/projects/sync.md index 46c66696c..a15549bd9 100644 --- a/docs/concepts/projects/sync.md +++ b/docs/concepts/projects/sync.md @@ -1,33 +1,47 @@ # 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, uv will raise an error 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 you add a dependency to your `pyproject.toml`, the lockfile will be considered +outdated. Similarly, if you change the version constraints for a dependency such that the locked +version is excluded, the lockfile will be considered outdated. However, if you change the version +constraints such that the existing locked version is still included, the lockfile will still be +considered up-to-date. -You can also check if the lockfile is up-to-date by passing the `--check` flag to `uv lock`: +You can check if the lockfile is up-to-date by passing the `--check` flag to `uv lock`: ```console $ uv lock --check @@ -35,10 +49,107 @@ $ uv lock --check This is equivalent to the `--locked` flag for other commands. -### Upgrading locked package versions +!!! important -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 + uv will not consider lockfiles outdated when new versions of packages are released — the lockfile + needs to be explicitly updated if you want to upgrade dependencies. See the documentation on + [upgrading locked package versions](#upgrading-locked-package-versions) for details. + +## 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, such that re-syncing 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 does not define a build system, it will not be installed. + See the [build systems](./config.md#build-systems) documentation 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 +``` + +### 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 +180,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 the +`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.