PURL Support

Which Package URL types FOSSA supports for SBOM import and generation, and how PURLs map to FOSSA's internal locator format.

4 min readUpdated Jul 9, 2026

Overview

A Package URL (PURL) is a standardized string used to identify software packages across different registries and ecosystems. Including PURLs in your SBOMs gives FOSSA a precise, unambiguous identifier for each component, enabling high-confidence license and vulnerability matching. Without PURLs, FOSSA falls back to CPE-based matching, which is less reliable. See Vulnerability Detection in Imported SBOMs for details.

The PURL format follows this pattern:

pkg:<type>/<namespace>/<name>@<version>?<qualifiers>#<subpath>

For the full specification, see the official PURL spec.

Supported PURL types

Package managers

FOSSA supports PURLs for the following package ecosystems. Types marked as FOSSA custom are not in the official PURL specification but are fully supported for SBOM import and generation.

PURL type	Ecosystem	Example
`apk`	Alpine Linux	`pkg:apk/alpine/curl@7.83.1-r2`
`cargo`	Rust	`pkg:cargo/tokio@1.21.0`
`cocoapods`	CocoaPods (iOS/macOS)	`pkg:cocoapods/AFNetworking@4.0.1`
`composer`	PHP	`pkg:composer/symfony/console@6.1.7`
`cran`	R	`pkg:cran/ggplot2@3.4.0`
`deb`	Debian / Ubuntu	`pkg:deb/debian/curl@7.74.0-1.3`
`gem`	RubyGems	`pkg:gem/rails@7.0.4`
`golang`	Go modules	`pkg:golang/github.com/gin-gonic/gin@1.8.1`
`hackage`	Haskell	`pkg:hackage/aeson@2.1.0.0`
`hex`	Hex (Elixir / Erlang)	`pkg:hex/phoenix@1.6.15`
`maven`	Maven (Java)	`pkg:maven/org.springframework/spring-core@5.3.23`
`npm`	npm (JavaScript)	`pkg:npm/express@4.18.2`
`nuget`	NuGet (.NET)	`pkg:nuget/Newtonsoft.Json@13.0.1`
`pub`	Pub (Dart / Flutter)	`pkg:pub/flutter@3.3.0`
`pypi`	Python	`pkg:pypi/django@4.1.3`
`rpm`	RPM (Red Hat / CentOS)	`pkg:rpm/redhat/curl@7.76.1-14.el9`
`swift`	Swift Package Manager	`pkg:swift/github.com/Alamofire/Alamofire@5.6.2`
`bower`	Bower (FOSSA custom)	`pkg:bower/jquery@3.6.0`
`cart`	Carthage (iOS/macOS) (FOSSA custom)	`pkg:cart/Alamofire@5.6.2`
`cpan`	Perl (FOSSA custom, based on draft spec)	`pkg:cpan/MIYAGAWA/Plack@1.0050`

Git repositories

The following git hosting platforms are supported as PURL types:

PURL type	Platform	Spec	Example
`github`	GitHub	Official	`pkg:github/facebook/react@18.2.0`
`bitbucket`	Bitbucket	Official	`pkg:bitbucket/atlassian/python-bitbucket@0.1`
`gitlab`	GitLab	FOSSA custom	`pkg:gitlab/gitlab-org/gitlab@15.0.0`
`gitee`	Gitee	FOSSA custom	`pkg:gitee/openeuler/kernel@5.10`
`googlesource`	Google Source	FOSSA custom	`pkg:googlesource/chromium/tools/depot_tools@main`
`sourceforge`	SourceForge	FOSSA custom	`pkg:sourceforge/dex-os@1.0`

Note

GitLab is not part of the official PURL specification, but FOSSA fully supports pkg:gitlab PURLs for both SBOM import and generation.

Generic PURLs for other git repositories

For git repositories hosted on platforms not listed above (self-hosted GitLab instances, Gitea, Gogs, or custom git servers) use pkg:generic with URL qualifiers:

# Using download_url
pkg:generic/package-name@version?download_url=https://git.example.com/repo.git

# Using vcs_url
pkg:generic/my-library@1.2.3?vcs_url=https://git.internal.company.com/team/my-library.git

Tip

If the repository is on GitHub, GitLab, or Bitbucket, use the specific PURL type rather than pkg:generic; you'll get better resolution and more reliable enrichment. Save pkg:generic for platforms that don't have their own type.

How FOSSA resolves PURLs

To enrich components with license and vulnerability data, FOSSA converts each PURL into its internal locator format. FOSSA's knowledge base, fetchers, and scanners operate on locators (not raw PURLs) so this conversion is required before any enrichment can occur.

FOSSA Locator Format

<fetcher>+<package>$<revision>

Git repository examples

PURL	FOSSA locator
`pkg:github/owner/repo@abc123`	`git+github.com/owner/repo$abc123`
`pkg:gitlab/owner/repo@def456`	`git+gitlab.com/owner/repo$def456`
`pkg:bitbucket/owner/repo@789xyz`	`git+bitbucket.org/owner/repo$789xyz`
`pkg:generic/lib@1.0?download_url=https://git.example.com/lib.git`	`url-private+{orgId}/https://git.example.com/lib.git$1.0`

Package manager examples

PURL	FOSSA locator
`pkg:npm/express@4.18.2`	`npm+express$4.18.2`
`pkg:maven/org.springframework/spring-core@5.3.23`	`mvn+org.springframework:spring-core$5.3.23`
`pkg:pypi/django@4.1.3`	`pip+django$4.1.3`

Best practices

For package managers:

Follow the naming conventions for the ecosystem; PyPI uses lowercase with hyphens, Maven requires the full namespace/name group-artifact format
Always include a specific version, avoid version ranges or wildcards
For ecosystems with namespaces (Maven, Go, Swift), include the full namespace

For git repositories:

Always specify the version as a full commit SHA or tag
Use the most specific PURL type available; fall back to pkg:generic only when no matching type exists
For pkg:generic, always include download_url or vcs_url so FOSSA can resolve the repository

Good examples:

pkg:github/facebook/react@18.2.0
pkg:gitlab/gitlab-org/gitlab-foss@15.0.0-ee
pkg:generic/internal-lib@v1.2.3?vcs_url=https://git.company.com/internal-lib.git

Avoid:

pkg:github/facebook/react: missing version
pkg:generic/internal-lib@1.2.3: missing URL qualifier

Troubleshooting

Found unsupported Purl type: <type>; the PURL type is not recognised by FOSSA. Use pkg:generic with URL qualifiers as a fallback.

PURL not converting correctly. Verify the PURL follows the correct format for its type, that required fields (namespace, version) are present, and for pkg:generic that a download_url or vcs_url qualifier is included.