Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

Common questions

Basics

Integrating

Problems

About

Basics

What's a package, project, or release?

We use a number of terms to describe software available on PyPI, like project, release, file, and package. Sometimes those terms are confusing because they're used to describe different things in other contexts. Here's how we use them on PyPI:

A project on PyPI is the name of a collection of releases and files, and information about them. Projects on PyPI are made and shared by other members of the Python community so that you can use them.

A release on PyPI is a specific version of a project. For example, the requests project has many releases, like requests 2.10 and requests 1.2.1. A release consists of one or more files.

A file, also known as a package, on PyPI is something that you can download and install. Because of different hardware, operating systems, and file formats, a release may have several files (packages), like an archive containing source code or a binary wheel.

How do I install a file (package) from PyPI?

To learn how to install a file from PyPI, visit the installation tutorial on the Python Packaging User Guide.

How do I package and publish my code for PyPI?

For full instructions on configuring, packaging and distributing your Python project, refer to the packaging tutorial on the Python Packaging User Guide.

What's a trove classifier?

Classifiers are used to categorize projects on PyPI. See https://pypi.org/classifiers/ for more information, as well as a list of valid classifiers.

Why do I need a verified email address?

Currently, PyPI requires a verified email address to perform the following operations:

  • Register a new project

The list of activities that require a verified email address is likely to grow over time.

This policy will allow us to enforce a key policy of PEP 541 regarding maintainer reachability. It also reduces the viability of spam attacks to create many accounts in an automated fashion.

You can manage your account's email addresses in your Profile. This also allows for sending a new confirmation email for users who signed up in the past, before we began enforcing this policy.

Integrating

Does PyPI have APIs I can use?

Yes, including RSS feeds of new packages and new releases. See the API reference.

How can I run a mirror of PyPI?

If you need to run your own mirror of PyPI, the bandersnatch project is the recommended solution. Note that the storage requirements for a PyPI mirror would exceed 1 terabyte—and growing!

How do I get notified when a new version of a project is released?

PyPI itself does not offer a way to get notified when a project uploads new releases. However, there are several third-party services that offer comprehensive monitoring and notifications for project releases and vulnerabilities listed as GitHub apps.

Where can I see statistics about PyPI, downloads, and project/package usage?

You can analyze PyPI download usage statistics via Google BigQuery.

Libraries.io provides statistics for PyPI projects (example, API) including GitHub stars and forks, dependency tracking (in progress), and other relevant factors.

For recent statistics on uptime and performance, see our status page.

Problems

I forgot my PyPI password. Can you help me?

If you've forgotten your PyPI password but you remember your email address or username, follow these steps to reset your password:

  1. Go to reset your password.
  2. Enter the email address or username you used for PyPI and submit the form.
  3. You'll receive an email with a password reset link.
  4. If you no longer have access to the email address associated with your account, file an issue on our tracker.

Note: All users submitting feedback, reporting issues or contributing to Warehouse are expected to follow the PyPA Code of Conduct.

Why am I getting "No matching distribution found" or "Could not fetch URL" errors during pip install?

Transport Layer Security, or TLS, is part of how we make sure connections between your computer and PyPI are private and secure. It's a cryptographic protocol that's had several versions over time. PyPI turned off support for TLS versions 1.0 and 1.1 in April 2018 (reason). If you are having trouble with pip install and get a No matching distribution found or Could not fetch URL error, try adding -v to the command to get more information:

pip install --upgrade -v pip

If you see an error like There was a problem confirming the ssl certificate or tlsv1 alert protocol version or TLSV1_ALERT_PROTOCOL_VERSION, you need to be connecting to PyPI with a newer TLS support library. The specific steps you need to take will depend on your operating system version, where your installation of Python originated (python.org, your OS vendor, or an intermediate distributor), and the installed versions of Python, setuptools, and pip. For help, go to the #pypa IRC channel on Freenode, file an issue at pypa/packaging-problems/issues, or post to the python-help mailing list, including your OS and installation details and the output of pip install --upgrade -vvv pip.

Note: All users submitting feedback, reporting issues or contributing to Warehouse are expected to follow the PyPA Code of Conduct.

I am having trouble using the PyPI website. Can you help me?

We take accessibility very seriously and want to make the website easy to use for everyone.

If you are experiencing an accessibility problem, report it to us on GitHub, so we can try to fix the problem, for you and others.

Note: All users submitting feedback, reporting issues or contributing to Warehouse are expected to follow the PyPA Code of Conduct.

Why can't I manually upload files to PyPI, through the browser interface?

In a previous version of PyPI, it used to be possible for maintainers to upload releases to PyPI using a form in the web browser. This feature was deprecated with the new version of PyPI – we instead recommend that you use twine to upload your project to PyPI.

How can I publish my private packages to PyPI?

PyPI does not support publishing private packages. If you need to publish your private package to a package index, the recommended solution is to run your own deployment of the devpi project.

Why isn't my desired project name available?

In some cases a publishing tool can return an error that the new project with desired name can't be created on PyPi. In addition, you may find that there is no associated project or release on pypi.org. Currently, there are three primary reasons this may occur:

  • The project name conflicts with a Python Standard Library module from any major version from 2.5 to present.
  • The project name has been explicitly prohibited by the PyPI administrators. For example, pip install requirements.txt is a common typo for pip install -r requirements.txt, and should not surprise the user with a malicious package.
  • The project name has been registered by another user, but no releases have been created.

How do I claim an abandoned or previously registered project name?

There is currently no established process for performing this administrative task that is explicit and fair for all parties. However, one is currently in development per PEP 541.

PEP 541 has been accepted, and PyPI is creating a workflow which will be documented here.

How can I upload a description in a different format?

By default, an upload's description will render with reStructuredText. If the description is in an alternate format like Markdown, a package may set the long_description_content_type in setup.py to the alternate format. Refer to the Python Packaging User Guide for details on the available formats.

PyPI will reject uploads if the description fails to render. To check a description locally for validity, you may use readme_renderer, which is the same description renderer used by PyPI.

How do I get a file size limit exemption or increase for my project?

If you can't upload your project's release to PyPI because you're hitting the upload file size limit, we can sometimes increase your limit. Make sure you've uploaded at least one release for the project that's under the limit (a developmental release version number is fine). Then, file an issue and tell us:

  • The name of the project
  • The size of your release, in megabytes
  • Which index/indexes you need the increase for (PyPI, Test PyPI, or both)

Note: All users submitting feedback, reporting issues or contributing to Warehouse are expected to follow the PyPA Code of Conduct.

Why did my package or user registration get blocked?

Spammers return to PyPI with some regularity hoping to place their Search Engine Optimized phishing, scam, and click-farming content on the site. Since PyPI allows for indexing of the Long Description and other data related to projects and has a generally solid search reputation, it is a prime target.

When the PyPI administrators are overwhelmed by spam or determine that there is some other threat to PyPI, new user registration and/or new project registration may be disabled. Check our status page for more details, as we'll likely have updated it with reasoning for the intervention.

Why am I getting a "Filename or contents already exists" or "Filename has been previously used" error?

PyPI will return these errors for one of these reasons:

  • Filename has been used and file exists
  • Filename has been used but file no longer exists
  • A file with the exact same content exists

PyPI does not allow for a filename to be reused, even once a project has been deleted and recreated.

To avoid this situation, use Test PyPI to perform and check your upload first, before uploading to pypi.org.

How do I request a new trove classifier?

If you would like to request a new trove classifier file a bug on our issue tracker. Include the name of the requested classifier and a brief justification of why it is important.

Note: All users submitting feedback, reporting issues or contributing to Warehouse are expected to follow the PyPA Code of Conduct.

Where can I report a bug or provide feedback?

We welcome constructive feedback and bug reports via our issue tracker. Before writing a new issue, first check that a similar issue does not already exist.

If you report a bug, provide as much detail as you can. For example:

  • Your operating system
  • Your browser and browser version
  • Your Python and pip version
  • Whether you can reproduce the bug (does it always happen, or just sometimes after certain actions?)
  • Steps to reproduce (if applicable)
  • Warning or error messages (if applicable)
  • What you expected to happen or your suggested fix (if you have one)

Note: All users submitting feedback, reporting issues or contributing to Warehouse are expected to follow the PyPA Code of Conduct.

About

Who maintains PyPI?

PyPI is powered by the Warehouse project; Warehouse is an open source project developed under the umbrella of the Python Packaging Authority (PyPA) and supported by the Python Packaging Working Group (PackagingWG).

The PyPA is an independent group of developers whose goal is to improve and maintain many of the core projects related to Python packaging.

The PackagingWG is a working group of the Python Software Foundation (PSF) whose goal is to raise and disburse funds to support the ongoing improvement of Python packaging. Most recently it secured an award from Mozilla whose funding enabled maintainers to improve Warehouse and launch the current version of PyPI.

What powers PyPI?

PyPI is powered by Warehouse and by a variety of tools and services provided by our generous sponsors.

Can I depend on PyPI being available?

As of April 16, 2018, PyPI.org is at "production" status, meaning that it has moved out of beta and replaced the old site (pypi.python.org). It is now robust, tested, and ready for expected browser and API traffic.

PyPI is heavily cached and distributed via CDN thanks to our sponsor Fastly and thus is generally available globally. However, the site is mostly maintained by volunteers, we do not provide any specific Service Level Agreement, and as could be expected for a giant distributed system, things can and sometimes do go wrong. See our status page for current and past outages and incidents. If you have high availability requirements for your package index, consider either a mirror or a private index.

How can I contribute to PyPI?

We have a huge amount of work to do to continue to maintain and improve PyPI (also known as the Warehouse project).

Financial: We would deeply appreciate your donations to fund development and maintenance.

Development: Warehouse is open source, and we would love to see some new faces working on the project. You do not need to be an experienced open-source developer to make a contribution – in fact, we'd love to help you make your first open source pull request!

If you have skills in Python, ElasticSearch, HTML, SCSS, or JavaScript, then skim our "Getting started" guide, then take a look at the issue tracker. We've created a 'Good first issue' label – we recommend you start here.

Issues are grouped into milestones; working on issues in the current milestone is a great way to help push the project forward. If you're interested in working on a particular issue, leave a comment and we can guide you through the contribution process.

Stay updated: You can also follow the ongoing development of the project on the distutils-sig mailing list and the PyPA Dev message group.

Note: All users submitting feedback, reporting issues or contributing to Warehouse are expected to follow the PyPA Code of Conduct.

How do I keep up with upcoming changes to PyPI?

Changes to PyPI are generally announced on both the pypi-announce mailing list and the PSF blog under the label "pypi". The PSF blog also has Atom and RSS feeds for the "pypi" label.

Resources

Looking for something not listed above? Perhaps these links will help:

Contact

The Python Packaging Authority (PyPA) is a working group who work together to improve Python packaging. If you'd like to get in touch with a core packaging developer, use #pypa on IRC (freenode), or join the distutils-sig mailing list.

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page