Skip to content

Project Metadata

Python packages can include additional metadata to provide more information about the project. This document outlines the specific behaviors implemented by PyPI to display project metadata and other details. The comprehensive list of metadata fields is available in the Python Packaging User Guide.

Project URLs

Packages owners can specify various URLs related to their project using the [project.urls] table in the package's pyproject.toml.

PyPI renders these URLs on the project page and splits them into verified and unverified subgroups. They are also available using the JSON API.

Verified details

Verified details

PyPI currently supports several ways of verifying project URLs. When a URL is verified, PyPI highlights it using a green checkmark ().

Warning

An URL being verified only attests that the URL is under control of the PyPI package owner at the time of verification, and does not imply any additional safety about that URL or any other relationship to the project in question.

URL verification occurs when release files are uploaded and is not repeated afterwards. This means the websites that verified URLs point to can change, and the URL will still show up as verified. The verified status only reflects control of the URL at the time of file upload, not at any later point.

The following subsections specify the different types of URLs that can be verified.

PyPI considers any URL pointing to that project on PyPI as verified. For example, the project page for pip will mark all of the following as verified:

  • https://pypi.org/project/pip/
  • https://pypi.org/p/pip/
  • https://pypi.python.org/project/pip
  • https://pypi.python.org/p/pip
  • https://python.org/pypi/pip

Via Trusted Publishing

Trusted Publishing allows PyPI to attest that the publishing 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/pip repository, the following URLs will be verified:
    • https://github.com/pypa/pip
    • https://github.com/pypa/pip/* (all subpaths)
    • https://github.com/pypa/pip.git
    • https://pypa.github.io/pip
    • https://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/pip repository, the following URLs will be verified:
    • https://gitlab.com/pypa/pip
    • https://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/pip
    • https://platform.activestate.com/pypa/pip/* (all subpaths)

Icons

Unverified details

While the labels or URLs can be arbitrary, PyPI recognizes the ones from the lists 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. The recognition patterns are case-insensitive. Items marked with an asterisk (*) indicate a prefix. It means that any name starting with the specified pattern will 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* , an URL pointing to Read the Docs domains or an URL starting with docs. or documentation.
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. Custom subdomains are also matched. For instance, if domain.com is listed, a URL ending in .domain.com will also match.

Service Icon Domain
Bitbucket bitbucket.org
GitHub github.com, github.io
GitLab gitlab.com
Google 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 reddit.com
Slack Slack* slack.com
Youtube youtube.com, youtu.be
Twitter twitter.com, x.com

Continuous Integration Services

To display a custom icon (), an entry URL must point to one of the service provider domains listed below. Custom subdomains are supported.

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 listed below.

Name Icon Domain
PyPI cheeseshop.python.org, pypi.io, pypi.org, pypi.python.org
Python python.org, *.python.org