# uv-resolver Resolution Modes: How uv Chooses Package Versions

> Explore uv-resolver modes: Highest, Lowest, and LowestDirect. Understand how uv selects package versions for optimal dependency resolution.

- Repository: [Astral/uv](https://github.com/astral-sh/uv)
- Tags: deep-dive
- Published: 2026-03-01

---

**`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)](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`](https://github.com/astral-sh/uv/blob/main/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.

```bash

# 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.

```bash

# 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.

```bash

# 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)](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.

```bash

# 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:

```rust
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`](https://github.com/astral-sh/uv/blob/main/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.