Registry / serialization / packageurl-python

packageurl-python

library0.17.6pypypi✓ verified 24d ago

packageurl-python is a Python library for parsing and building Package URLs (purls), a standardized way to identify software packages across various ecosystems. It is currently at version 0.17.6 and maintains an active development pace with frequent patch and minor releases.

serialization

pip install packageurl-python

github ↗package ↗

INSTALL

IMPORT

SIG · PACKAGEURL-PYTHON

packageurl-python

serializationpythonv0.17.6

Install

1.6s avg

Import

49ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.17.6 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.052s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.046s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PackageURL

✓ from packageurl import PackageURL

Demonstrates how to parse a Package URL string into a PackageURL object, access its individual components, and then convert it back to a dictionary or string. It also shows how to construct a PackageURL object from its constituent parts.

from packageurl import PackageURL # Create a PackageURL from a string purl_string = "pkg:maven/org.apache.commons/io@1.3.4?checksum=25b8109d" purl = PackageURL.from_string(purl_string) # Access components print(f"Type: {purl.type}") print(f"Namespace: {purl.namespace}") print(f"Name: {purl.name}") print(f"Version: {purl.version}") print(f"Qualifiers: {purl.qualifiers}") print(f"Subpath: {purl.subpath}") # Convert to dictionary or string print(f"As dict: {purl.to_dict()}") print(f"As string: {purl.to_string()}") # Build a PackageURL from components new_purl = PackageURL(type='npm', name='react', version='18.2.0', qualifiers={'foo': 'bar'}) print(f"New PURL: {new_purl.to_string()}")

Debug

Known issues

breakingSupport for Python 3.7 was dropped in version 0.16.0. Users on Python 3.7 or older must upgrade their Python environment to at least 3.8 before upgrading to `packageurl-python` 0.16.0 or newer.

fix

Upgrade Python to 3.8 or newer, or pin `packageurl-python<0.16.0`.

affects: >=0.16.0

breakingThe `purl2url` utility's support for generating download URLs for `qpkg` package types was removed in version 0.17.5. Code relying on this specific conversion will break.

fix

Review `purl2url` usage, especially for `qpkg` types. Alternative methods for generating `qpkg` download URLs may be required.

affects: >=0.17.5

gotchaPrior to version 0.17.0, parsing of package names and namespaces containing colons might have been incorrect. Ensure that PURLs with colons are parsed as expected, especially if migrating from older versions.

fix

Upgrade to `packageurl-python` 0.17.0 or newer to correctly handle colons in names and namespaces.

affects: <0.17.0

gotchaThe `url2purl` and `purl2url` utility functions frequently receive updates and behavior changes across minor versions (e.g., adding support for new URL patterns, removing support for others). Relying heavily on their exact output for all possible inputs may lead to unexpected results on upgrades.

fix

Thoroughly test `url2purl` and `purl2url` behavior after any `packageurl-python` upgrade, particularly for critical parsing or generation flows.

affects: All versions, especially across minor releases

gotchaVersion 0.17.2 introduced an `encode` keyword argument to the `.to_string()` method. If you rely on specific encoding behavior for your PURL strings, you might need to explicitly set this argument for consistency or to handle special characters.

fix

Consider explicitly using the `encode` argument in `.to_string()` for predictable output, e.g., `purl.to_string(encode=True)`.

affects: <0.17.2

Errors

Common errors & fixes

ImportError: No module named packageurl

This error occurs when the 'packageurl-python' library is not installed in your Python environment or is not accessible in the current execution path.

fix

Install the library using pip: `pip install packageurl-python`

ValueError: Invalid purl 'pkg:generic/Foo:%20%3CBar%3E@1.2.3' cannot contain a "user:pass@host:port" URL Authority component: ''

This error typically arises when attempting to create a PackageURL from a string that contains characters (like colons or slashes in names/namespaces) which are not properly URL-encoded, leading to an invalid PURL structure upon parsing or round-tripping.

fix

Ensure all components of the PURL are correctly URL-encoded before passing them to `PackageURL.from_string()` or when constructing a `PackageURL` object. For example, use `urllib.parse.quote_plus()` for problematic characters in individual components if you are building the PURL string manually.

AttributeError: can't set attribute

PackageURL objects are immutable after creation, meaning you cannot directly modify their attributes (like `type`, `name`, `version`, etc.) once an instance has been created.

fix

To 'change' a PackageURL, create a new PackageURL instance with the desired modifications instead of attempting to alter an existing one. For example, use the existing object's attributes to construct a new one with the updated value.

ValueError: A purl string argument is required.

This error occurs when the `PackageURL.from_string()` method is called with an argument that is `None`, an empty string, or a string containing only whitespace.

fix

Ensure that the string passed to `PackageURL.from_string()` is a non-empty string containing a valid or at least parsable PURL.

Upgrade

Version history

0.17.6latest on PyPI · released Nov 24, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/package-url/packageurl-python ↗

packagehttps://pypi.org/project/packageurl-python/ ↗