packageurl-python

packageurl-python is the reference Python implementation of the Package URL (purl) specification. A purl is a standardized, ecosystem-agnostic identifier for a software package — for example pkg:maven/org.apache.commons/io@1.3.4 — and this library parses those strings into structured components and builds them back from parts.

Beyond the core PackageURL type, it includes contrib helpers to convert between purls and download/repository URLs (url2purl and purl2url), plus integrations for Django model fields and SQLAlchemy. It is widely used across software composition analysis, SBOM, and vulnerability tooling that needs a consistent way to reference packages.

What You Get

• A PackageURL type to parse, validate, normalize, and build purl strings
• url2purl and purl2url converters between download/repo URLs and Package URLs
• Django model field and SQLAlchemy integrations for storing purls
• Conformance with the official purl-spec test suite

Common Use Cases

• Generating consistent package identifiers for SBOMs and dependency inventories
• Normalizing package references in software composition analysis and vulnerability tooling
• Converting between repository/download URLs and canonical Package URLs

Under The Hood

Architecture - The core lives in src/packageurl/init.py, defining the PackageURL type (a normalized namedtuple/dataclass with type, namespace, name, version, qualifiers, subpath) plus percent-encoding helpers built on urllib.parse and normalization routines. The contrib package layers converters: url2purl.py and purl2url.py use a small route dispatcher (route.py) to map URLs to purls and back, with framework helpers under contrib/django and contrib/sqlalchemy.

Tech Stack - Pure Python packaged with setuptools (setup.cfg/setup.py). It relies only on the standard library for the core; optional extras enable the Django and SQLAlchemy integrations. It ships a py.typed marker and uses modern typing (overloads, Self, Literal under TYPE_CHECKING).

Code Quality - Correctness is anchored to the shared purl-spec: tests/ includes test_purl_spec.py running the official cross-language conformance suite alongside unit tests for the API and contrib converters. The code is fully typed and licensed cleanly with per-file SPDX headers.

API Design - The public API is small and intuitive: PackageURL.from_string, to_string, to_dict, and construction from keyword parts. Round-tripping is symmetric, and the contrib converters follow the same clear function-based interface, keeping the learning curve low for anyone who understands the purl format.