Qualifiers are key and value pairs after the question mark in a purl. Common keys are checksum, download_url, file_name, repository_url, vcs_url and vers. The project's guidance says to keep them few and limited to what is needed to identify the package accurately, so purls stay compact and readable.
What qualifiers are for
A purl has a type, optional namespace, name and optional version. Some packages cannot be identified by those alone. A Debian package needs its architecture. A container image needs its registry. Qualifiers carry that extra detail, and each type defines which keys it uses.
The purl specification also warns against the temptation to cram package attributes into them. The guidance says qualifiers should be a minimal set required for accurate identification.
The common keys
| Key | What it holds | Notes from the guidance |
|---|---|---|
| checksum | One or more checksums, comma separated | Each item is lowercase algorithm, colon, lowercase hex value |
| download_url | A direct package download URL | For when you need the exact artifact location |
| file_name | The file name of a package archive | For file level identification, the subpath component is preferred |
| repository_url | The repository where the package lives | Use when the type has no default repository or has several common ones |
| vcs_url | A version control location | Follows pip style syntax or the SPDX package download location |
| vers | A version range instead of a single version | Mutually exclusive with the version component |
Checksum example
The guidance shows the shape with shortened values.
checksum=sha1:ad9503c3e994a4f,sha256:41bf9088b3a1e6c1ef1d
Use a checksum when you must prove that two systems mean the same bytes, not merely the same version number.
The vers qualifier for ranges
A single purl normally points at one version. For vulnerability reporting and dependency analysis you often need a range. The vers qualifier handles this and cannot be combined with a version in the same purl. Its value follows the separate version range specification.
The guidance gives this example for Django.
pkg:pypi/django?vers=vers:pypi%2F%3E%3D1.11.0%7C%21%3D1.11.1%7C%3C2.0.0
Decoded, the range reads as 1.11.0 or later, not 1.11.1, and below 2.0.0. The symbols are percent encoded inside the purl, which is why the string looks unreadable. Always decode before you interpret it.
How to use qualifiers in your own tool
- Read keys case insensitively by lowercasing, as the parsing rules do.
- Ignore keys you do not understand instead of failing, but keep them when you re-emit the purl.
- Compare purls after normalization, not as raw strings, since order of qualifiers and encoding can differ.
- Do not match vulnerabilities on repository_url or download_url. They describe where a package came from, not which package it is.
- When you build a purl, add a qualifier only if the type definition asks for it or ambiguity would result.
Try it yourself
Click through it at your own pace, or open it full screen. Follow how a component identity leads to a list of affected and fixed versions.
Where this fits
Qualifiers are the part of a purl most likely to differ between two tools describing the same component. See matching VEX statements to SBOM components with purl. Safeguard offers SBOM and dependency scanning, and the free scan lets you inspect real component identifiers.
Quick check
Can I use both version and vers in one purl?
No. The guidance says the vers qualifier is mutually exclusive with the version component.
Should I add many qualifiers to be safe?
No. The guidance says to keep them limited to what accurate identification needs.
Sources
Last reviewed: 19 October 2026.
