Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

uv Resolution Errors: Reading No solution found and Lock Drift

The last Because clause is the contradiction and everything above it is context. Then decide: relax a pin, narrow requires-python, or change index strategy.

~5 min readPython
#Python#uv#Dependencies#Packaging
3D illustration of dependency cubes resolved through a solver funnel into a lockfile slab

Introduction & Quick Summary

Symptom. uv sync or uv lock stops with × No solution found when resolving dependencies: followed by a tree of Because … lines and And because …, ending in we can conclude that the requirements are unsatisfiable. Related messages include The lockfile at 'uv.lock' needs to be updated, but the --frozen flag was provided, error: Failed to download distribution …, No solution found when resolving dependencies for split (markers: python_full_version >= '3.13'), and Because there is no version of torch available for linux-aarch64 ….

Cause. The constraints cannot all hold at once: two packages pin incompatible versions of a third, a requires-python range excludes the version a dependency needs, a marker splits resolution by platform and one branch is unsatisfiable, or index priority hides the package that would satisfy the requirement (uv prefers the first index that has the package name, not the version you wanted). A lockfile error is different — it means pyproject.toml changed and uv.lock was not regenerated.

Fix. Read the explanation tree from the last line upwards; it names the exact pair of requirements in conflict. Then choose: relax the pin, add [tool.uv] override-dependencies for a transitive conflict, narrow requires-python, or change index strategy when a private index shadows PyPI.

Core Mechanics, Signatures & Reproducible Setup

uv resolves the whole graph at once, for all platforms and Python versions allowed by requires-python. It prefers the highest version that satisfies every constraint, reads indexes in priority order, and writes exactly what it chose into uv.lock. A "universal" lock carries markers so one lockfile serves macOS, Linux and Windows, which means a conflict on a platform you never build for still fails the lock.

Reproduce a conflict in a scratch project:

bash
mkdir -p /tmp/uvdemo && cd /tmp/uvdemo cat > pyproject.toml <<'EOF' [project] name = "uvdemo" version = "0.1.0" requires-python = ">=3.11" dependencies = [ "fastapi==0.115.0", "pydantic==1.10.18", ] EOF uv lock # × No solution found when resolving dependencies: # ╰─▶ Because fastapi==0.115.0 depends on pydantic>=1.7.4,<3.0.0 ... # and you require pydantic==1.10.18 ...

Read the tree bottom-up. The last Because clause is the one that closes the contradiction; everything above it is context. uv also prints the resolution it attempted for each fork, which is how you tell a global conflict from a marker-specific one.

bash
uv lock -v 2>&1 | tail -40 # version attempts per candidate uv tree # what the current lock actually contains uv pip check # installed-vs-declared mismatches

Key Comparison Table

MessageMeaningFix
No solution found when resolving dependenciesGlobal conflictRelax a pin or add an override
... for split (markers: …)Conflict on one platform/Python branchAdd a marker-specific constraint
The lockfile … needs to be updatedpyproject.toml changeduv lock, or drop --frozen
Failed to download distributionIndex or networkCheck index URL, retry, --offline if cached
There is no version of X that satisfies …Marker excludes every buildWiden requires-python or pin a platform build
Because your project requires X and no versions …Name typo or missing indexCheck the package name and [[tool.uv.index]]
CommandWhenEffect
uv lock --upgrade-package fooOne dependency staleRe-resolves only that package's subtree
uv lock --upgradeFull refreshIgnores existing lock constraints
uv sync --lockedCIFails if the lock would change
uv sync --frozenDeployUses the lock without checking pyproject.toml
uv add "foo<2"New constraintEdits pyproject.toml and relocks

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. A direct pin that blocks a transitive minimum

toml
[project] dependencies = ["pydantic==1.10.18", "fastapi==0.115.0"]
toml
# Fixed: let the framework choose the major, pin only the floor dependencies = ["pydantic>=2.7,<3", "fastapi==0.115.0"]

Deleting the pin entirely is often the correct answer: the point of a lockfile is to pin the resolved version, so the direct requirement does not need ==. Keep == only for packages whose behaviour you have verified against a version.

2. requires-python that excludes a dependency

toml
requires-python = ">=3.9" dependencies = ["numpy>=2.2"] # numpy 2.2 requires Python >= 3.10

uv reports Because numpy>=2.2 requires Python >=3.10 and your project requires Python >=3.9, we can conclude …. Fix by narrowing the project's range (>=3.10) or by making the dependency conditional:

toml
dependencies = [ "numpy>=2.2; python_version >= '3.10'", "numpy>=1.26,<2.0; python_version < '3.10'", ]

3. Marker-split resolution failures

toml
dependencies = [ "torch==2.4.1; platform_machine == 'x86_64'", "torch==2.4.1; platform_machine == 'arm64'", ]

If a package publishes no wheels for one branch, the lock fails for the whole project even though your CI only builds one platform. Options: restrict the project to the platforms you deploy ([tool.uv] environments = ["sys_platform == 'linux'"]), or split the dependency by marker so the unsupported branch is simply absent.

toml
[tool.uv] environments = ["sys_platform == 'linux'", "sys_platform == 'darwin'"]

4. Index priority versus version

toml
[[tool.uv.index]] name = "internal" url = "https://pypi.internal.example.com/simple" default = true [tool.uv] index-strategy = "unsafe-best-match"

By default uv prefers the first index that has a package name, even if a later index has a newer version. If your internal mirror carries an old requests, uv happily resolves that old version and every constraint that needs a newer one conflicts. unsafe-best-match lets uv consider all indexes; the name says why — a dependency-confusion attack becomes possible if a private name also exists publicly. The safer fix is to give the internal index explicit = true and reference it per package with [tool.uv.sources].

5. Lockfile drift between machines and CI

code
# CI error: The lockfile at `uv.lock` needs to be updated, but `--frozen` was provided. To update the lockfile, run `uv lock`.

--frozen means "do not read pyproject.toml at all", so any edit to dependencies is ignored rather than rejected. --locked is the CI flag you want: it uses the lock and fails when it is stale. A related failure is --frozen passing while the deployed environment installs something different, because someone edited pyproject.toml without relocking and the lock is silently authoritative.

6. Transitive conflicts you do not control

toml
[tool.uv] override-dependencies = ["urllib3>=2.2.2"] constraint-dependencies = ["idna<4"]

constraint-dependencies tightens a version without adding a requirement; override-dependencies replaces what a transitive requirement asks for. Use constraints first — they keep the dependency graph honest — and reach for overrides only when a package pins a range that is wrong for your environment. Both are recorded in the lock, so uv tree shows the result.

Common Compilation/Runtime Mistakes & Version Gotchas

MistakeSymptomCorrect approach
pip install and uv sync in the same projectTwo sources of truthOne tool per environment
Editing pyproject.toml without uv lock--frozen uses stale depsuv lock then commit
== pins on every direct dependencyConflicts on the next upgradePin floors, let the lock pin exact versions
--index-strategy unsafe-best-match by reflexDependency confusion riskexplicit = true per index
Deleting uv.lock to fix a conflictResolution drifts from CI--upgrade-package for one package
Assuming uv respects pip.confUnexpected index[[tool.uv.index]] in pyproject.toml
No requires-pythonUniversal resolution covers old versionsDeclare the floor you support

Version notes: uv's lock format has changed across minor releases and older versions refuse a newer lock with The lockfile at uv.lock was created with an incompatible version — pin uv itself in CI (uv==0.9.* or a uv.lock version check) so a runner update does not rewrite the file. index-strategy accepted unsafe-first-match as the old default name; current releases call the default first-index and reject the older spelling in some configs. uv pip compile remains the pip-compatible path for projects that cannot move to pyproject.toml, but it does not read [tool.uv] sources, which is the usual reason a compile succeeds locally and fails in CI.

For the surrounding work, the YAML validator catches the [[tool.uv.index]] table indented into the wrong TOML section (a failure that looks like a network error), the text diff tool compares a uv.lock before and after an upgrade to see exactly which packages moved, and the JSON formatter reads uv export --format requirements-txt output when you need to hand a resolved set to a pip-based image.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.