Common mistakes with uv workspace lockfile resolution

Clearly, uv workspaces require a distinct name for the root even if developers set package = false. The tool registers the root name as a workspace member identity, so the root name cannot match any member package name. If a developer uses the same name for the root and a core package, uv sync fails. To resolve inter-package dependencies, developers must add a [tool.uv.sources] entry for the local package. Without this entry, uv sync fails to find the local dependency. When using pytest with importlib mode in a monorepo, developers must avoid adding init.py to test directories. Adding these files causes a silent bug where pytest resolves two files to the same cached module.

The Rust-built resolver provides significant speed advantages over Python-based tools. In a benchmark testing a 47-dependency project, uv resolved dependencies 16 times faster than Poetry. This tool replaces pip, pip-tools, pipx, Poetry, pyenv, and virtualenv with a single binary. Developers manage Python versions through the built-in uv python command. This command downloads and installs specific CPython builds without requiring a system package manager or pyenv. For those using the uv pip interface, the tool produces platform-specific resolution by default, similar to pip-tools. As of September 2026, uv is version 0.12.12.

Single version enforcement and resolution logic

Easily the best part of uv’s workspace model is the enforcement of a single version for every package across all services. This constraint exposes version conflicts that a per-environment pip setup hides from teams. While pip allows Service A to run one version of a library and Service B to run another, uv requires one truth for the whole workspace. Developers must align these versions across all services before they start the migration. This process prevents version drift but demands more upfront work than traditional isolated environments.

Teams migrating from pip often encounter significant dependency bloat because uv installs every declared dependency while the old pip approach only added the package source to the Python path without actually installing its dependencies. You know the issues with dependency drift in monorepos. To solve this, developers should use optional dependencies to separate service-specific needs from library requirements. Using uv sync –extra <name> allows developers to install dependencies for a specific optional group.

The uv resolver also behaves differently regarding Python versions. When evaluating requires-python ranges, uv only considers lower bounds and ignores upper bounds. If a project specifies requires-python = ">=3.8", the resolver ignores any upper limits. During universal resolution, uv selects the latest compatible version for each supported Python version. If the latest version of a dependency requires Python 3.9, uv selects that for users on 3.9 but picks a previous version for users on 3.8. Furthermore, the project’s requires-python must be a subset of the requires-python of all its dependencies. By default, uv prefers stable versions over pre-releases.

Docker deployment and editable install fixes

Developers easily avoid the Docker editable install trap by building wheels for local packages first. The trap itself causes import errors in multi-stage builds. When uv export generates requirements, it includes local paths for workspace packages. These paths create .pth files that reference source directories in the file system. In a multi-stage Docker build, the final stage lacks these source directories. This leads to unpredictable import failures during Python startup. Will the workspace model eventually replace the need for manual version alignment?

Wheels are self-contained and extract directly to site-packages. When developers use uv sync, the tool installs the local package as editable automatically, which works well for local development but fails in production containers. To ensure successful production deployments, teams must build all internal packages into wheels before the final image is produced.