Resolution in UV

What Resolution Is

• Process of converting requirements into specific package versions that fulfill all constraints and dependencies.
• Ensures compatibility across direct and transitive dependencies.

Dependency Types

• Direct dependencies: Declared in your project.
• Transitive dependencies: Introduced by other dependencies.

Resolution Examples

• Conflict resolution: If foo needs lib>=1.0.0 and bar needs lib>=2.0.0, only lib 2.0.0 is valid.
• Multiple valid solutions: If foo 2.0.0 needs lib==2.0.0 and bar 2.0.0 needs lib==1.0.0, foo 1.0.0 + bar 2.0.0 or foo 2.0.0 + bar 1.0.0 are both valid.

Platform Markers

• Used to specify conditional dependencies based on environment (e.g., bar ; python_version < "3.9").

Resolution Modes

• Platform-specific:
  • Used by uv pip compile by default.
  • Resolves based on the current or specified platform and Python version.
• Universal:
  • Used for uv.lock.
  • Platform-agnostic, resolving for all OSes and Python versions.
  • Allows multiple versions per package with markers.

Constraining Resolution

• Use [tool.uv.environments] to limit resolution platforms.
• Use [tool.uv.required-environments] to require platform compatibility for packages lacking source distributions.

Resolution Preferences

• UV prefers versions in existing lockfile or already installed.
• To override, use --upgrade, --resolution lowest, or --resolution lowest-direct.

Fork Strategy

• requires-python (default): Chooses latest compatible per Python version.
• fewest: Minimizes number of versions (increases cross-platform consistency).

Pre-release Handling

• Pre-releases used only if:
  • They are directly requested.
  • No stable versions exist.
• For others, use --prerelease allow.

Dependency Constraints vs Overrides

• Constraints: Narrow valid versions (--constraint constraints.txt).
• Overrides: Replace declared requirements (e.g., [tool.uv.override-dependencies]).

Dependency Metadata

• Used when a package has no static metadata or source-only distribution.
• Provide via [tool.uv.dependency-metadata].

Example:

[[tool.uv.dependency-metadata]]
name = "chumpy"
version = "0.70"
requires-dist = ["numpy>=1.8.1", "scipy>=0.13.0", "six>=1.11.0"]

Lower Bounds

• UV adds lower bounds by default when using uv add.
• Important for reproducibility and avoiding resolution to outdated or incompatible versions.

Reproducibility

• Use --exclude-newer DATE to pin resolution to package versions available before a specific date.
• Format: 2006-12-02 or 2006-12-02T02:07:43Z.

Source Distribution Support

UV supports:

• .tar.gz, .tgz
• .tar.bz2, .tbz
• .tar.xz, .txz
• .tar.zst
• .tar.lz, .tar.lzma
• .zip

Lockfile Versioning

• Lockfile format versioned with a version field.
• Minor uv upgrades may introduce new schema versions.
• Lockfiles from future versions will be rejected; older schema may be read if compatible.