packaging

Warnings

• breaking LegacyVersion and LegacySpecifier were removed in 22.0. packaging.version.parse() now raises InvalidVersion for non-PEP 440 version strings instead of silently returning a LegacyVersion object.
  Fix: Wrap Version() / parse() calls in a try/except InvalidVersion block. Migrate any non-PEP 440 version strings to compliant ones.
• breaking SpecifierSet and Specifier were moved from packaging.version to packaging.specifiers in an early release. Importing from packaging.version will fail.
  Fix: Use: from packaging.specifiers import SpecifierSet, Specifier
• breaking Optional metadata.Metadata attributes now default to None (changed in 24.0). Code checking for empty-string defaults will silently mishandle absent fields.
  Fix: Guard attribute access with `if metadata.summary is not None` rather than truthiness checks.
• gotcha SpecifierSet.filter() and Specifier.contains() exclude pre-releases by default unless the specifier itself includes a pre-release version. Pass prereleases=True explicitly to include them.
  Fix: spec.filter(versions, prereleases=True) or SpecifierSet('>=1.0', prereleases=True)
• gotcha canonicalize_name() returns a NormalizedName (typing.NewType of str). Mixing raw strings and NormalizedName values causes mypy errors. Always canonicalize before comparing package names.
  Fix: Compare only after canonicalization: canonicalize_name(a) == canonicalize_name(b)
• gotcha The library uses calendar versioning (YY.N), not semver. There is no reliable way to determine whether a release contains breaking changes from the version number alone.
  Fix: Pin to an exact version in production tooling, e.g. packaging==26.0, and review the changelog on each upgrade.
• gotcha packaging has no runtime dependencies since 21.0 (pyparsing was removed and replaced with a hand-written parser). Do not add pyparsing as a workaround for older compatibility issues.
  Fix: No extra dependencies needed. Just pip install packaging.

Install

• pip install packaging Python

Imports

• Version

  from packaging.version import Version

  LegacyVersion was removed in 22.0. Version() now raises InvalidVersion for non-PEP 440 strings instead of returning a LegacyVersion.
• parse

  from packaging.version import Version, parse

  In <22.0, parse() could return LegacyVersion for invalid versions. Since 22.0, parse() raises InvalidVersion for non-PEP 440 strings — it no longer silently returns a LegacyVersion.
• SpecifierSet

  from packaging.specifiers import SpecifierSet

  Specifier support was moved out of packaging.version into packaging.specifiers in an early breaking release. Always import from packaging.specifiers.
• Requirement

  from packaging.requirements import Requirement

• canonicalize_name

  from packaging.utils import canonicalize_name

  Returns NormalizedName (a NewType of str). Useful for reliable package name comparison. Pass validate=True to also reject invalid distribution names.
• Marker

  from packaging.markers import Marker

Quickstart

Core usage of packaging 26.x: version parsing, specifier matching, requirement parsing, and name canonicalization.

from packaging.version import Version
from packaging.specifiers import SpecifierSet
from packaging.requirements import Requirement
from packaging.utils import canonicalize_name

# Parse and compare PEP 440 versions
v = Version('1.2.3')
print(v.major, v.minor, v.micro)  # 1 2 3
print(v.is_prerelease)             # False

# Check if a version satisfies a specifier
spec = SpecifierSet('>=1.0,<2.0')
print(v in spec)                   # True

# Parse a PEP 508 requirement string
req = Requirement('requests[security]>=2.28; python_version>="3.8"')
print(req.name)      # requests
print(req.extras)    # {'security'}
print(req.specifier) # >=2.28
print(req.marker)    # python_version >= "3.8"

# Normalize a package name (PEP 503)
print(canonicalize_name('Django'))          # django
print(canonicalize_name('oslo.concurrency')) # oslo-concurrency