uv-resolver Resolution Modes: How uv Chooses Package Versions

uv-resolver supports three resolution modes—Highest (default), Lowest, and LowestDirect—that control whether the resolver selects the newest, oldest, or a hybrid combination of package versions during dependency resolution.

The ResolutionMode enum defined in [crates/uv-resolver/src/resolution_mode.rs](https://github.com/astral-sh/uv/blob/main/crates/uv-resolver/src/resolution_mode.rs) determines how the uv package manager selects compatible versions when resolving dependencies. This setting directly impacts which versions of direct and transitive dependencies are installed in your environment.

The Three Resolution Strategies

The resolver translates the ResolutionMode enum into an internal ResolutionStrategy (lines 29‑40 of resolution_mode.rs) that drives version selection. Each mode serves different testing and compatibility needs.

Highest (Default)

Highest selects the latest compatible version for every requirement, including both direct dependencies specified in your project and transitive dependencies pulled in indirectly.

This is the default behavior for all uv commands unless explicitly overridden. It ensures you receive the most recent bug fixes and features that satisfy your version constraints.

# Explicitly use highest resolution (though this is the default)

uv pip install "requests>=2.0" --resolution highest

Lowest

Lowest selects the oldest compatible version for all dependencies, including transitive ones.

Use this mode to test the minimum declared bounds of your dependencies. It helps verify that your project works against the oldest versions you claim to support, catching compatibility issues with legacy APIs early.

# Resolve the lowest possible versions for every package

uv pip install "requests>=2.0" --resolution lowest

LowestDirect

LowestDirect selects the lowest compatible version for direct dependencies while maintaining the highest compatible version for transitive (indirect) dependencies. Build‑time dependencies are always resolved to the newest version regardless of this setting.

This hybrid approach lets you test the lowest direct constraints specified in your project while still benefiting from the latest bug fixes and security patches in transitive dependencies.

# Resolve lowest versions only for direct dependencies

uv pip install "requests>=2.0" --resolution lowest-direct

How Resolution Modes Work Internally

The ResolutionMode enum is converted into a ResolutionStrategy via the ResolutionStrategy::from_mode method. This strategy carries any additional data required for resolution, such as the set of direct dependencies needed for the LowestDirect variant.

The selected strategy then drives the version‑selection algorithm in the resolver core located in [crates/uv-resolver/src/options.rs](https://github.com/astral-sh/uv/blob/main/crates/uv-resolver/src/options.rs), which holds the resolution_mode field propagating the enum into the resolver configuration.

Using Resolution Modes in Practice

Command Line Interface

The --resolution flag accepts highest, lowest, or lowest-direct across uv commands including uv pip install, uv pip sync, and project synchronization commands.

# Default highest resolution

uv pip install django

# Test against oldest dependencies

uv pip install django --resolution lowest

# Test lowest direct dependencies only

uv pip install django --resolution lowest-direct

Programmatic Usage (Rust)

When using uv's resolver as a library, configure the mode via the Options struct:

use uv_resolver::{Options, ResolutionMode};

// Create resolver options with the desired mode
let opts = Options::default()
    .resolution_mode(ResolutionMode::Lowest);   // or .Highest, .LowestDirect

// Pass `opts` to the resolver API (e.g., Resolver::new(...).solve(...))

Summary

• Highest (default): Installs the newest compatible versions for all dependencies, ensuring access to latest features and fixes.
• Lowest: Installs the oldest compatible versions for all dependencies, useful for testing minimum version bounds.
• LowestDirect: Installs the oldest compatible versions for direct dependencies while using the newest versions for transitive dependencies, balancing constraint testing with transitive security updates.

The resolution mode is defined in crates/uv-resolver/src/resolution_mode.rs and controlled via the --resolution CLI flag or the ResolutionMode enum in Rust code.

Frequently Asked Questions

What is the default resolution mode in uv?

The default resolution mode is Highest. When you run uv pip install without specifying --resolution, uv selects the latest compatible version for every dependency, both direct and transitive. This behavior is hardcoded as the default variant in the ResolutionMode enum.

When should I use the lowest resolution mode?

Use --resolution lowest when you need to verify that your project works against the minimum declared version bounds of your dependencies. This is essential for library authors who want to ensure compatibility with the oldest versions they claim to support, catching API incompatibilities that might not appear when testing against latest versions.

How does lowest-direct differ from lowest resolution?

LowestDirect (activated with --resolution lowest-direct) resolves direct dependencies to their lowest compatible versions while resolving transitive dependencies to their highest compatible versions. In contrast, Lowest resolves all dependencies—both direct and transitive—to their lowest compatible versions. The LowestDirect mode is useful for testing your direct constraints while still benefiting from recent bug fixes in dependencies of your dependencies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}