Description:

Currently, if upgrade is requested, uv lock/sync --locked/--check fails with the following error:

error: The lockfile at uv.lock needs to be updated, but --locked was provided. To update the lockfile, run uv lock.

I was initially surprised by this, because I thought if no updates are available for any packages, the lockfile shouldn't need to change.
However, the code seems to suggest otherwise, or I misunderstood and it is actually a bug. I am not sure why this was done, but I guess searching the web to determine whether updates are available is not an option, or maybe it simply cannot be done. Either way, I can live with that. However, this means, it is always known that if upgrade==true and --locked/--check is provided, the command cannot succeed. So my suggestion would be to either add more specific error message or provide additional context as warning for this specific case.

Minimum Reproducible Example:

uv init foo && cd foo && uv lock && uv lock --locked --upgrade

While the above is quite unlikely, the following is less so:

uv init foo && cd foo && uv lock && echo "\n[tool.uv]\nupgrade = true" >> pyproject.toml && uv lock --locked

# pyproject.toml
[project]
name = "foo"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13.0"
dependencies = []

[tool.uv]
upgrade=true

Actual Behavior:

Initialized project `foo` at `/home/sayandip/github/uv/foo`
Using CPython 3.13.0
Resolved 1 package in 13ms
Using CPython 3.13.0
Creating virtual environment at: .venv
Resolved 1 package in 10ms
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided. To update the lockfile, run `uv lock`.

Expected Behavior:

Initialized project `foo` at `/home/sayandip/github/uv/foo`
Using CPython 3.13.0
Resolved 1 package in 13ms
Using CPython 3.13.0
Creating virtual environment at: .venv
warning: Failed to validate existing lockfile: The lockfile needs to be updated when `upgrade` is requested. Either disable upgrade in settings, or pass `--no-upgrade`.
Resolved 1 package in 10ms
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided. To update the lockfile, run `uv lock`.

Or,

Initialized project `foo` at `/home/sayandip/github/uv/foo`
Using CPython 3.13.0
Resolved 1 package in 27ms
Using CPython 3.13.0
Creating virtual environment at: .venv
error: The lockfile at `uv.lock` needs to be updated when `upgrade` is requested, either omit `--locked` to update the lockfile, or pass `--no-upgrade` to disable update.

System Information:

Ubuntu 24.04.1 LTS (via WSL2 on win11)
uv 0.5.13
WSL Info:
WSL version: 2.3.26.0
Kernel version: 5.15.167.4-1
Windows version: 10.0.27764.1000

NOTE: The docs say the following:

.... This means that locked or installed versions will not change unless an incompatible version is requested or an upgrade is explicitly requested with --upgrade.

Technically, one can still interpret this as:

locked or installed versions may or may not change if an incompatible version is requested or an upgrade is explicitly requested with --upgrade.