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

Improve lockfile concept documentation, add coverage for upgrades (#6698)

This commit is contained in:
Zanie Blue 2024-08-27 11:20:53 -05:00 committed by GitHub
parent 18453ae79f
commit cee0d2daf5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 45 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
docs/concepts/projects.md
View File

@ -69,7 +69,7 @@ use [`uvx`](../guides/tools.md) or
managed = false
```
## Lockfile
## Project lockfile
uv creates a `uv.lock` file next to the `pyproject.toml`.
@ -77,23 +77,6 @@ uv creates a `uv.lock` file next to the `pyproject.toml`.
installed across all possible Python markers such as operating system, architecture, and Python
version.
If your project supports a more limited set of platforms or Python versions, you can constrain the
set of solved platforms via the `environments` setting, which accepts a list of PEP 508 environment
markers. For example, to constrain the lockfile to macOS and Linux, and exclude Windows:
```toml title="pyproject.toml"
[tool.uv]
environments = [
"sys_platform == 'darwin'",
"sys_platform == 'linux'",
]
```
Entries in the `environments` setting must be disjoint (i.e., they must not overlap). For example,
`sys_platform == 'darwin'` and `sys_platform == 'linux'` are disjoint, but
`sys_platform == 'darwin'` and `python_version >= '3.9'` are not, since both could be true at the
same time.
Unlike the `pyproject.toml`, which is used to specify the broad requirements of your project, the
lockfile contains the exact resolved versions that are installed in the project environment. This
file should be checked into version control, allowing for consistent and reproducible installations
@ -110,10 +93,38 @@ The lockfile is created and updated during uv invocations that use the project e
There is no Python standard for lockfiles at this time, so the format of this file is specific to uv
and not usable by other tools.
### Checking if the lockfile is up-to-date
To avoid updating the lockfile during `uv sync` and `uv run` invocations, use the `--frozen` flag.
To assert the lockfile is up-to-date, use the `--locked` flag. If the lockfile is not up-to-date, an
error will be raised instead of updating the lockfile.
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.
### Upgrading locked package versions
By default, uv will prefer the locked versions of packages when running `uv sync` and `uv lock`.
Package versions will only change if project's dependency constraints exclude the previous, locked
version. To upgrade to the latest package versions supported by the project's dependency
constraints, use `uv lock --upgrade`.
### Limited resolution environments
If your project supports a more limited set of platforms or Python versions, you can constrain the
set of solved platforms via the `environments` setting, which accepts a list of PEP 508 environment
markers. For example, to constrain the lockfile to macOS and Linux, and exclude Windows:
```toml title="pyproject.toml"
[tool.uv]
environments = [
"sys_platform == 'darwin'",
"sys_platform == 'linux'",
]
```
Entries in the `environments` setting must be disjoint (i.e., they must not overlap). For example,
`sys_platform == 'darwin'` and `sys_platform == 'linux'` are disjoint, but
`sys_platform == 'darwin'` and `python_version >= '3.9'` are not, since both could be true at the
same time.
## Managing dependencies
@ -151,6 +162,20 @@ To update an existing dependency, e.g., to add a lower bound to the `httpx` vers
$ uv add 'httpx>0.1.0'
```
!!! note
"Updating" a dependency refers to changing the constraints for the dependency in the
`pyproject.toml`. The locked version of the dependency will only change if necessary to
satisfy the new constraints. To force the package version to update to the latest within
the constraints, use `--upgrade-package <name>`, e.g.:
```console
$ uv add 'httpx>0.1.0' --upgrade-package httpx
```
See the [lockfile](#upgrading-locked-package-versions) section for more details on upgrading
package versions.
Or, to change the bounds for `httpx`:
```console