{"id":1263,"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":"python","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,"search_vec":"'0.17.6':34 'across':26 'activ':38 'build':15 'chain':51 'current':31 'develop':39 'ecosystem':28 'frequent':42 'identifi':23 'librari':4,11 'maintain':36 'minor':45 'pace':40 'packag':1,16,25 'packageurl':6,47 'packageurl-python':5 'pars':13 'parser':53 'patch':43 'purl':18,48 'python':3,7,10 'releas':46 'sbom':52 'secur':49 'softwar':24 'standard':20 'suppli':50 'url':2,17 'various':27 'version':33 'way':21","created_at":"2026-04-06T16:57:01.989240+00:00","updated_at":"2026-04-16T17:50:44.491215+00:00","problems":[{"fix":"Install the library using pip: `pip install packageurl-python`","cause":"This error occurs when the 'packageurl-python' library is not installed in your Python environment or is not accessible in the current execution path.","error":"ImportError: No module named packageurl"},{"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.","cause":"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.","error":"ValueError: Invalid purl 'pkg:generic/Foo:%20%3CBar%3E@1.2.3' cannot contain a \"user:pass@host:port\" URL Authority component: ''"},{"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.","cause":"PackageURL objects are immutable after creation, meaning you cannot directly modify their attributes (like `type`, `name`, `version`, etc.) once an instance has been created.","error":"AttributeError: can't set attribute"},{"fix":"Ensure that the string passed to `PackageURL.from_string()` is a non-empty string containing a valid or at least parsable PURL.","cause":"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.","error":"ValueError: A purl string argument is required."}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.17.6","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/package-url/packageurl-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/packageurl-python/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}