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.

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:
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.
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 mismatchesKey Comparison Table
| Message | Meaning | Fix |
|---|---|---|
No solution found when resolving dependencies | Global conflict | Relax a pin or add an override |
... for split (markers: …) | Conflict on one platform/Python branch | Add a marker-specific constraint |
The lockfile … needs to be updated | pyproject.toml changed | uv lock, or drop --frozen |
Failed to download distribution | Index or network | Check index URL, retry, --offline if cached |
There is no version of X that satisfies … | Marker excludes every build | Widen requires-python or pin a platform build |
Because your project requires X and no versions … | Name typo or missing index | Check the package name and [[tool.uv.index]] |
| Command | When | Effect |
|---|---|---|
uv lock --upgrade-package foo | One dependency stale | Re-resolves only that package's subtree |
uv lock --upgrade | Full refresh | Ignores existing lock constraints |
uv sync --locked | CI | Fails if the lock would change |
uv sync --frozen | Deploy | Uses the lock without checking pyproject.toml |
uv add "foo<2" | New constraint | Edits pyproject.toml and relocks |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. A direct pin that blocks a transitive minimum
[project]
dependencies = ["pydantic==1.10.18", "fastapi==0.115.0"]# 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
requires-python = ">=3.9"
dependencies = ["numpy>=2.2"] # numpy 2.2 requires Python >= 3.10uv 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:
dependencies = [
"numpy>=2.2; python_version >= '3.10'",
"numpy>=1.26,<2.0; python_version < '3.10'",
]3. Marker-split resolution failures
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.
[tool.uv]
environments = ["sys_platform == 'linux'", "sys_platform == 'darwin'"]4. Index priority versus version
[[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
# 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
[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
| Mistake | Symptom | Correct approach |
|---|---|---|
pip install and uv sync in the same project | Two sources of truth | One tool per environment |
Editing pyproject.toml without uv lock | --frozen uses stale deps | uv lock then commit |
== pins on every direct dependency | Conflicts on the next upgrade | Pin floors, let the lock pin exact versions |
--index-strategy unsafe-best-match by reflex | Dependency confusion risk | explicit = true per index |
Deleting uv.lock to fix a conflict | Resolution drifts from CI | --upgrade-package for one package |
Assuming uv respects pip.conf | Unexpected index | [[tool.uv.index]] in pyproject.toml |
No requires-python | Universal resolution covers old versions | Declare 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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.