{"library":"packageurl-python","title":"Package URL Python Library","description":"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.","status":"active","version":"0.17.6","language":"en","source_language":"en","source_url":"https://github.com/package-url/packageurl-python","tags":["packageurl","purl","security","supply chain","sbom","parser"],"install":[{"cmd":"pip install packageurl-python","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"PackageURL","correct":"from packageurl import PackageURL"}],"quickstart":{"code":"from packageurl import PackageURL\n\n# Create a PackageURL from a string\npurl_string = \"pkg:maven/org.apache.commons/io@1.3.4?checksum=25b8109d\"\npurl = PackageURL.from_string(purl_string)\n\n# Access components\nprint(f\"Type: {purl.type}\")\nprint(f\"Namespace: {purl.namespace}\")\nprint(f\"Name: {purl.name}\")\nprint(f\"Version: {purl.version}\")\nprint(f\"Qualifiers: {purl.qualifiers}\")\nprint(f\"Subpath: {purl.subpath}\")\n\n# Convert to dictionary or string\nprint(f\"As dict: {purl.to_dict()}\")\nprint(f\"As string: {purl.to_string()}\")\n\n# Build a PackageURL from components\nnew_purl = PackageURL(type='npm', name='react', version='18.2.0', qualifiers={'foo': 'bar'})\nprint(f\"New PURL: {new_purl.to_string()}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.8 or newer, or pin `packageurl-python<0.16.0`.","message":"Support 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.","severity":"breaking","affected_versions":">=0.16.0"},{"fix":"Review `purl2url` usage, especially for `qpkg` types. Alternative methods for generating `qpkg` download URLs may be required.","message":"The `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.","severity":"breaking","affected_versions":">=0.17.5"},{"fix":"Upgrade to `packageurl-python` 0.17.0 or newer to correctly handle colons in names and namespaces.","message":"Prior 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.","severity":"gotcha","affected_versions":"<0.17.0"},{"fix":"Thoroughly test `url2purl` and `purl2url` behavior after any `packageurl-python` upgrade, particularly for critical parsing or generation flows.","message":"The `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.","severity":"gotcha","affected_versions":"All versions, especially across minor releases"},{"fix":"Consider explicitly using the `encode` argument in `.to_string()` for predictable output, e.g., `purl.to_string(encode=True)`.","message":"Version 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.","severity":"gotcha","affected_versions":"<0.17.2"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}