Advanced

Dependency ranges and resolution

A library declares what it needs, an application declares what it uses, and a resolver picks a version that satisfies both. When it cannot, the error names the two ranges that do not overlap, and reading that is the whole skill of a broken install.

What you will see

True - a needs at least 1.4, b needs below 1.4, so nothing satisfies both. That is the error to read, not to guess past.

About 1 min of reading

Try It

Find the conflict.

1

Two ranges

a = (1.4, None); b = (None, 1.4) print('overlap:', a[0] is not None and b[1] is not None and a[0] > b[1])

Before you run it, say out loud what it will print. Then open the answer.

What it prints
True - a needs at least 1.4, b needs below 1.4, so nothing satisfies both. That is the error to read, not to guess past.

Data Flow

Ranges resolve to one version.
1 Declare the ranges
↓
2 Collect all constraints
↓
3 Find the overlap
↓
4 Print the chosen version
Line by line

Read the first example one line at a time. A line that prints shows what appears on screen; the rest set things up quietly.

a = (1.4, None); b = (None, 1.4) sets nothing on screen
print('overlap:', a[0] is not None and b[1] is not None and a[0] > b[1]) True - a needs at least 1.4, b needs below 1.4, so nothing satisfies both. That is the error to read, not to guess past.
Why this works
Ask the resolver

A command that prints the chosen version for every dependency is the state of an install. Publishing that output with a release is what makes the release reproducible.

Test at the edges

Install with the lowest allowed version of each dependency. A test that only passes at newest is a test that hides a range that is too wide.

Examples

Read the conflict

The resolver says A needs >=1.4 and B needs <1.4. Those two ranges do not overlap, so no version exists. The fix is changing one of the declarations, not trying a new number.

Widen costs

A range that allows any major is a range that will accept a breaking change. Narrowing to the majors you tested is what makes an upgrade a decision rather than an accident.

One version per process

Two parts of a system needing different majors of the same library cannot both be satisfied in one process. That is a design problem, and the resolver error is the only place it is visible.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← Migrating saved data
Previous Lesson
Migrating saved data
Next Lesson
Withdrawing a release
Withdrawing a release →