Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 38 ยท pyproject and Metadata

Version Specifiers and Environment Markers

Master PEP 440 versions, pre-releases, compatible release (~=), specifier sets and environment markers using the packaging library with live examples.

Dependencies are only useful if you can say which versions work and where. Python has a precise, standardized language for this: versions (PEP 440), specifiers that constrain them, and markers that make requirements conditional on the environment. All three are implemented by the packaging library, which pip itself uses, so what you try here is real.

What a version looks like

A PEP 440 version has up to five parts:

TEXT
[N!]N(.N)*[{a|b|rc}N][.postN][.devN][+local]
 1.2.3        release segment
 1.2.3rc1     release candidate (pre-release)
 1.2.3.post1  post-release (a packaging fix)
 1.2.3.dev4   developmental release
 1!2.0        epoch (rare)
 1.2.3+ubuntu1  local version (never on PyPI)

Sorting follows the rules you would expect, with the twist that pre-releases come before the final: 1.0.dev1 < 1.0a1 < 1.0b1 < 1.0rc1 < 1.0 < 1.0.post1. Trailing zeros do not matter: 1.0 == 1.0.0.

Python Parsing and sorting 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 loose v1 is accepted by Version because the leading v is allowed in normalization; 1.2.x and banana are not. Normalization also rewrites spellings: 1.0-alpha1 becomes 1.0a1.

Specifiers

A specifier is an operator plus a version. Several, separated by commas, must all hold.

Specifier Meaning
==1.4.2 exactly that version (ignoring trailing zeros)
==1.4.* any 1.4.x
!=1.4.3 anything except
>=1.4, >1.4, <=2, <2 ordering
~=1.4.2 compatible release: >=1.4.2, ==1.4.*
~=1.4 compatible: >=1.4, ==1.*
===foo arbitrary string equality (avoid)

~= ("compatible release") is the most useful for libraries that follow semantic versioning: it allows bug-fix and feature updates but not the next major. The number of segments you write matters, so ~=2.2 allows 2.9 but ~=2.2.0 does not.

Python Checking versions against 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.

That last point surprises people. When selecting among candidate releases, filter() (and pip) skip pre-releases unless the specifier itself mentions one (>=1.5rc1), only pre-releases exist, or you opt in (--pre in pip, prereleases=True here). Merely testing a single version with in looks only at the numbers, so check is_prerelease yourself when it matters.

Picking the newest allowed release

This is what an installer does for each package: filter all available versions through the specifier set, then take the largest.

Python A tiny version resolver

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.

When the combined set matches nothing, pip reports a resolution conflict. That is the whole mechanism behind the error.

Environment markers

Markers add conditions after a semicolon in a requirement: colorama; sys_platform == "win32". They can test:

Marker Example value
python_version "3.12"
python_full_version "3.12.4"
sys_platform "linux", "win32", "darwin"
platform_system "Linux", "Windows", "Darwin"
platform_machine "x86_64", "arm64"
implementation_name "cpython", "pypy"
os_name "posix", "nt"
extra the requested extra, e.g. "yaml"

Operators are comparisons plus in, not in, and boolean and/or.

Python Evaluating markers for different environments

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.

marker.evaluate() with no argument uses the real current environment. Passing a dictionary lets you ask "what would happen on Windows?" without being on Windows, which is how lock tools build cross-platform resolutions.

flowchart LR
    R["Requirement:<br/>tomli>=2; python_version &lt; '3.11'"] --> E{"Evaluate marker<br/>for this interpreter"}
    E -- true --> I["Install tomli>=2"]
    E -- false --> S["Skip it"]

Markers are evaluated on the user's machine at install time, so one wheel can support many setups.

Choosing constraints for your own project

  • Direct dependencies: use a lower bound you tested (>=2.30), and an upper bound only for known incompatibilities or for a major version you have not tried (<3). Needless upper caps cause resolver conflicts across the ecosystem.
  • requires-python: lower bound only, matching your CI matrix.
  • Applications: pin exact versions in a lock file; ranges are for the metadata.
  • Use ~= when a library promises semantic versioning and you want security fixes automatically.

Version numbers are for machines and humans alike. Pick a scheme (semantic versioning or calendar versioning) and apply it consistently; see Versioning and Changelogs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which version is the SMALLEST?

    Order: 1.0.dev1 < 1.0rc1 < 1.0 < 1.0.post1. A developmental release sorts before everything else for that number.
  2. 2. What does ~=2.4 allow?

    Compatible release: >=2.4, ==2.*. With three segments (~=2.4.1) it means >=2.4.1 and <2.5.
  3. 3. When pip chooses among releases for >=1.0, are pre-releases such as 1.5rc1 considered by default?

    Selection skips pre-releases by default. A final release is preferred when one satisfies the constraints.
  4. 4. What does the marker in 'tomli>=2; python_version < "3.11"' do?

    Python 3.11 added tomllib, so older versions need the backport.

Summary

  • PEP 440 versions have release, pre-release, post-release, dev and local parts, and sort in a defined order.
  • Specifiers (==, !=, >=, ~=, ==1.*) combine with commas; all must hold.
  • Installers skip pre-releases by default (--pre or prereleases=True opts in).
  • Markers make requirements conditional on platform, Python version, implementation or extras.
  • packaging (Version, SpecifierSet, Marker, Requirement) is the same code pip uses.
  • Prefer lower bounds and avoid needless upper caps in library metadata.

Next: Build Backends Compared