Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 38 ยท Dependency Management

Version Specifiers and PEP 440

Learn how Python versions are written and compared, how specifiers like ~=, >=, <, != and == work, and how to test them with the packaging library.

Every dependency you declare comes with a rule about which versions are acceptable. "Any version of requests" is risky, because a future release may break your code. "Exactly requests==2.31.0" is safe today but blocks every security fix. The art of dependency management is choosing rules between those two extremes, and that starts with understanding how Python writes and compares versions.

Python's version format is defined by PEP 440, and the packaging library (the same one pip uses) implements it. In this lesson you will parse versions, compare them, and build specifier sets, all with real code.

Lesson 1 of this part of the course explained why we declare dependencies at all. Here we focus on the language of version rules. The next lessons build on it: resolving conflicts and lock files.

What a version looks like

A PEP 440 version has up to five parts:

TEXT
[epoch!]release[aN|bN|rcN][.postN][.devN][+local]
   1!    2.4.1     rc2       .post1   .dev3   +ubuntu
  • release: dotted numbers such as 2.4.1. This is the part you see most.
  • pre-release: a (alpha), b (beta) or rc (release candidate), followed by a number. 2.0rc1 comes before 2.0.
  • post-release: .post1 marks a tiny fix after a release (a packaging mistake, for example). It sorts after the release.
  • dev release: .dev3 is a snapshot before even the pre-releases.
  • local version: +cu121 after a plus sign is a build label. Public indexes such as PyPI reject it.
  • epoch: 1! resets ordering when a project once changed its numbering scheme. You will rarely meet one.

Python versions are not the same as the semantic versioning (SemVer) you may know from other ecosystems. 1.0.0.1 is valid, 1.0 equals 1.0.0, and 1.0.post1 exists. The packaging.version.Version class handles all of that for you.

Python Parse and compare versions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The last two comparisons show why you should never compare versions as strings. As text, "1.10" is smaller than "1.9" because "1" is less than "9"; as versions, it is larger.

Version specifiers

A specifier is one comparison operator plus a version. Several specifiers separated by commas form a specifier set, and a version must satisfy all of them.

Specifier Meaning Example
==1.4.2 exactly this version pins one release
!=1.5.0 anything except this skips a known-bad release
>=1.4 this version or newer sets a floor
<2.0 older than this sets a ceiling
~=1.4.2 compatible release >=1.4.2, <1.5
==1.4.* prefix match any 1.4.x
===lit arbitrary string match an escape hatch, almost never used

The compatible release operator ~= deserves attention. The number of release segments you write decides the ceiling: ~=1.4.2 allows 1.4.3 and 1.4.9, but not 1.5; ~=1.4 allows 1.9 but not 2.0. It is a handy way to say "bug fixes yes, breaking changes no" when the project follows a conventional scheme.

Python Test specifier sets

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice the pre-release behavior of filter(), the method installers use to choose among candidates. When a final release satisfies the rule, 2.1.0rc1 is skipped. It is offered only if you opt in (pip install --pre, or prereleases=True here), if the rule itself names a pre-release (>=2.0.0rc1), or if nothing else could satisfy the rule. This protects you from accidentally running unfinished code. (contains() answers a narrower question, "does this one version match the specifier?", and recent releases of packaging accept a pre-release there.)

Requirement strings

In pyproject.toml and requirements.txt you write a whole requirement: a name, optional extras, a specifier set, and optionally an environment marker.

TEXT
requests[socks]>=2.31,<3 ; python_version >= "3.9"
  • requests is the distribution name (normalized: case and -, _, . are interchangeable).
  • [socks] selects an extra, an optional group of additional dependencies.
  • >=2.31,<3 is the specifier set.
  • After the semicolon comes a marker: a condition on the platform or Python version. The requirement only applies when the marker is true.
Python Parse requirement strings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Name normalization matters when you compare names yourself: Typing_Extensions and typing-extensions are the same project.

Choosing good ranges

Specifiers express a policy. Some rules of thumb:

  1. Libraries (things others depend on) should use wide ranges: requests>=2.28. Tight pins in a library make it impossible to combine with other packages. Add an upper bound only when you know a newer major version breaks you.
  2. Applications (things you deploy) should use wide ranges in pyproject.toml and exact versions in a lock file. The ranges say what you tested against; the lock says what you actually installed.
  3. Prefer >=X.Y plus a <N ceiling on the next major version if the project is known to follow SemVer. Use ~= when the compatible-release meaning fits.
  4. Exclude single bad releases with != rather than pinning to avoid them.
  5. Never write == for a library's dependency unless you must, and never depend on a pre-release in a published package without saying why.

An overly strict upper bound such as numpy<2 in a library can break an entire user environment the day a new major version appears and another package needs it. Add ceilings sparingly, and remove them once you have tested the new major version.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which statement about PEP 440 ordering is true?

    A post-release is a small fix after the final release, so it sorts after it. Pre-releases and dev releases sort before the final version, and numbers are compared numerically.
  2. 2. What does ~=2.3.4 allow?

    The compatible-release operator with three segments is shorthand for >=2.3.4, <2.4. With two segments (~=2.3) the ceiling would be 3.0.
  3. 3. Why is comparing version strings with > a bad idea?

    Strings compare character by character. Use packaging.version.Version, which compares the numeric parts correctly.
  4. 4. A library you publish should usually declare its dependencies with

    Wide ranges let users combine your library with others. Exact versions belong in an application's lock file.

Summary

  • A PEP 440 version has a release part plus optional pre, post, dev, local and epoch parts; compare them with packaging.version.Version, never as strings.
  • Specifiers (==, !=, >=, <, ~=, ==1.4.*) combine with commas, and a version must satisfy all of them.
  • Pre-releases are ignored unless requested.
  • A requirement adds a name, extras and an environment marker after a semicolon; names are normalized.
  • Libraries use wide ranges, applications add exact versions through a lock file.

Next: Resolving Dependencies and Conflicts