Project Metadata
Python packages can include additional metadata to provide more informationabout the project. This document outlines the specific behaviorsimplemented by PyPI to display project metadata and other details. Thecomprehensive list of metadata fields is available in thePython PackagingUser Guide.
Project URLs
Packages owners can specify various URLs related to their project usingthe[project.urls] table in the package'spyproject.toml.
PyPI renders these URLs on the project page and splits them intoverified andunverified subgroups. They are also available using theJSON API.
Verified details
PyPI currently supports several ways of verifying project URLs. When a URL is verified, PyPI highlights it using a green checkmark ().
Warning
A URL being verified only attests that the URL is under control of thePyPI package owner at the time of verification, and does not imply anyadditional safety about that URL or any other relationship to the projectin question.
URL verification occurs when release files are uploaded and is not repeatedafterwards. This means the websites that verified URLs point to can change,and the URL will still show up as verified. The verified status only reflectscontrol of the URLat the time of file upload, not at any later point.
The following subsections specify the different types of URLs that can be verified.
Self-links
PyPI considers any URL pointing to that project on PyPI as verified.For example, the project page forpip will mark all of thefollowing as verified:
https://pypi.org/project/pip/https://pypi.org/p/pip/https://pypi.python.org/project/piphttps://pypi.python.org/p/piphttps://python.org/pypi/pip
Via Trusted Publishing
Trusted Publishing allows PyPI to attest that thepublishing workflow for a package is coming from a verified source.
The URLs that can be verified depend on the Trusted Publisher used:
- GitHub Actions: Packages uploaded using GHA from a repository will have the GitHub URLs for that repository verified. For example, for the
pypa/piprepository, the following URLs will be verified:https://github.com/pypa/piphttps://github.com/pypa/pip/*(all subpaths)https://github.com/pypa/pip.githttps://pypa.github.io/piphttps://pypa.github.io/pip/*(all subpaths)
- GitLab CI/CD: Packages uploaded using GitLab CI/CD from a repository will have the GitLab URLs for that repository verified. For example, for the
pypa/piprepository, the following URLs will be verified:https://gitlab.com/pypa/piphttps://gitlab.com/pypa/pip/*(all subpaths)https://gitlab.com/pypa/pip.git
- Google Cloud: No Google-specific URLs are currently verified.
- ActiveState: Packages uploaded using ActiveState will have URLs linked to the project in ActiveState verified:
https://platform.activestate.com/pypa/piphttps://platform.activestate.com/pypa/pip/*(all subpaths)
Icons
While the labels or URLs can be arbitrary, PyPI recognizes the ones from thelists below and changes the default icon from to a customized one.
General URL
To display a custom icon, an entry must match one of the pattern. Therecognition patterns are case-insensitive. Items marked with an asterisk (*)indicate a prefix. It means that any name starting with the specified patternwill be recognized.
| Name | Icon | Description | Aliases |
|---|---|---|---|
| Homepage | For the project homepage | ||
| Download | A download link | ||
| Changelog | Changelog information | Change log, Changes, Release notes, News, What's new, History | |
| Documentation* | Project documentation | Docs* , a URL pointing toRead the Docs domains or a URL starting withdocs. ordocumentation. | |
| Bug* | Bug/Issue report location | Issue*, Tracker*, Report* | |
| Funding* | Sponsoring information | Sponsor*, Donation*, Donate* |
Hosting Platforms
An entry URL must point to a domain below to display a custom icon. Customsubdomains are also matched. For instance, ifdomain.com is listed, a URLending in.domain.com will also match.
| Service | Icon | Domain |
|---|---|---|
| Bitbucket | bitbucket.org | |
| GitHub | github.com,github.io | |
| GitLab | gitlab.com | |
google.com |
Social Media Platforms
To display a custom icon, an entry must either :
- have its name match the case-insensitive pattern listed
- a URL pointing to a listed domain (custom subdomains are supported)
| Platform | Icon | Name | Domain |
|---|---|---|---|
| Discord | discord.com,discordapp.com,discord.gg | ||
| Gitter | gitter.im | ||
| Mastodon | Mastodon | ||
reddit.com | |||
| Slack | Slack* | slack.com | |
| Youtube | youtube.com,youtu.be | ||
twitter.com,x.com | |||
| Bluesky | Bluesky | bsky.app |
Continuous Integration Services
To display a custom icon (), an entry URL mustpoint to one of the service provider domains listed below. Custom subdomains aresupported.
| Service | Domain |
|---|---|
| AppVeyor | ci.appveyor.com |
| CircleCI | circleci.com |
| Codecov | codecov.io |
| Coveralls | coveralls.io |
| Travis CI | travis-ci.com,travis-ci.org |
Python Ecosystem
To display a custom icon, an entry URL must point to one of the domain listedbelow.
| Name | Icon | Domain |
|---|---|---|
| PyPI | cheeseshop.python.org,pypi.io,pypi.org,pypi.python.org | |
| Python | python.org,*.python.org |