uv lock --upgrade-package PKG: update one dependency in uv.lock

uv lock --upgrade-package idna (short -P) re-resolves only idna, moving it to the newest version allowed by pyproject.toml, and keeps every other entry in uv.lock where it was. Without the flag, uv lock deliberately keeps locked versions that still satisfy the requirements, so relaxing a bound in pyproject.toml does not by itself upgrade anything. --upgrade (-U) is the "upgrade everything" counterpart. The same flags work for uv sync and uv run.

Locked version, relaxed bound, upgrade

cat > pyproject.toml <<'EOF'
[project]
name = "demo"
version = "0.1.0"
requires-python = ">=3.9"
dependencies = ["idna>=3,<3.8"]
EOF
uv lock -q
grep -A1 'name = "idna"' uv.lock | tail -1
sed -i 's/<3.8/<3.9/' pyproject.toml
echo "--- uv lock (bound relaxed)"
uv lock -q
grep -A1 'name = "idna"' uv.lock | tail -1
echo "--- uv lock --upgrade-package idna"
uv lock --upgrade-package idna 2>&1 | grep -vE "^(Resolved|Using CPython)"
grep -A1 'name = "idna"' uv.lock | tail -1

version = "3.7"
--- uv lock (bound relaxed)
version = "3.7"
--- uv lock --upgrade-package idna
Updated idna v3.7 -> v3.8
version = "3.8"

After the bound was relaxed, uv lock kept 3.7 because it still satisfies <3.9. Only --upgrade-package moved it, and uv prints the change it made.

Upgrade options

Typical workflow

uv lock --upgrade-package requests   # update one dependency
uv sync                              # install it
uv run pytest                        # test
git add uv.lock && git commit -m "Upgrade requests"

pyproject.toml is not edited: the declared range stays the same, only the locked version changes. To raise the minimum version in pyproject.toml as well, use uv add 'requests>=2.33'; see uv add.

Pitfalls

• An upgrade that conflicts with other constraints fails with No solution found when resolving dependencies, naming the package that holds it back.
• After upgrading, CI with uv sync --locked passes only if the new uv.lock is committed; otherwise it fails with The lockfile needs to be updated.
• uv pip compile --upgrade-package exists too, for requirements.txt workflows, with the same semantics.

FAQ