Skip to content
Browse

/errors/uv/lockfile-needs-to-be-updated-locked

uv: error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided

verified onenvironmentlocal · windows 10.0.26200 arm64 · GNU bash 5.3.15 (Git Bash) · uv 0.12.19 (bea138450 2026-09-24 aarch64-pc-windows-msvc)updated
tool
uv
exit code
1
versions
uv 0.4 – 0.12
os
any

error: The lockfile at uv.lock needs to be updated, but --locked was provided. means pyproject.toml no longer matches uv.lock, and --locked tells uv to fail instead of updating the lockfile. This is the check you want in CI. Run uv lock on your machine and commit the updated uv.lock; the next uv sync --locked passes.

Reproduce it

bash
cat > pyproject.toml <<'EOF'
[project]
name = "demo"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = []
EOF
uv lock -q
# add a dependency without re-locking
sed -i 's/dependencies = \[\]/dependencies = ["six==1.16.0"]/' pyproject.toml
uv lock --locked 2>&1 | grep -v '^Resolved'
exit "${PIPESTATUS[0]}"

Output · exit 1

Using CPython 3.13.15
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.

hint: To update the lockfile, run `uv lock`.

uv sync --locked and uv run --locked print the same error.

Fix

bash
cat > pyproject.toml <<'EOF'
[project]
name = "demo"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["six==1.16.0"]
EOF
uv lock -q
uv lock --locked -q
echo "locked check exit=$?"

Output

locked check exit=0

--locked vs --frozen

FlagChecks uv.lock against pyproject.tomlUpdates uv.lockUse it for
(none)yesyes, when neededLocal development
--lockedyes, fails on mismatchneverCI: guarantees the committed lock is current
--frozennoneverInstalling from uv.lock as is, for example in a Docker layer before the source is copied

Sources

Related pages

errors · uvuv: error: No `pyproject.toml` found in current directory or any parent directoryuv add, uv sync and uv lock need a project: without pyproject.toml they fail with No pyproject.toml found. Run uv init, cd into the project, or use uv pip.commands · uvuv init: create a new Python project with uvuv init NAME creates a Python project with pyproject.toml, README, .python-version and git. The --app, --lib, --package, --bare and --script layouts compared.errors · pnpmERR_PNPM_OUTDATED_LOCKFILE Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to dateERR_PNPM_OUTDATED_LOCKFILE means package.json changed but pnpm-lock.yaml was not regenerated, and CI installs with frozen-lockfile. Run pnpm install and commit.flags · uvuv sync --no-dev: install a project without its dev dependenciesuv sync --no-dev installs runtime dependencies only and removes the dev group from .venv. Group options, --locked, --no-install-project, Dockerfile, pitfalls.