In today’s article, we are going to discuss how PyPI lets developers share packages with other people who may wish to use that particular functionality in their own applications. Additionally, we are going to introduce a step-by-step guide to help you upload your Python package on PyPi so that it is available to every Python user. I’ll use a real end-to-end example so that all the steps are crystal clear.
The Python Package Index, abbreviated as PyPI, is the official repository of software for the Python programming language. By default,
pip — which is the most popular Python package manager — uses PyPI as the source for retrieving package dependencies.
PyPI lets you find, install and even publish your Python packages so that they are widely available to the public. More than 300,000 different packages are currently published in the index with more than 2,500,000 releases being distributed to users.
If you are using Python 2 ≥ 2.7.9 or Python 3 ≥ 3.4
pip should be already installed. But if for any reason you may need to install it simply run the commands below (instructions are suitable for Unix):
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
And that’s it! You can ensure that
pip is now installed as below.
$ python -m pip --version
pip X.Y.Z from .../site-packages/pip (python X.Y)
I created a sample project on GitHub so that it’s easier to demonstrate how to publish your own packages on PyPI. Normally you’ll need to create at least the files below:
README.rst: It is highly recommended to include a README file where you should outline the basic functionality offered by your package. Additionally, you may also include installation instructions or a usage guide.
setup.py file for our example project is as follows.
from setuptools import setup, find_packages
setup.cfg: This file contains default options for
[metadata] description-file=README.md license_files=LICENSE.rst
The overall structure of our example project is shown below
. ├── LICENSE.txt ├── README.rst ├── setup.cfg ├── setup.py ├── src │ ├── test_pypi_medium │ │ ├── __init__.py │ │ └── example │ │ ├── __init__.py │ │ └── custom_sklearn.py ├── tests │ ├── __init__.py │ └── example │ ├── __init__.py │ └── test_custom_sklearn.py
Now we just need to publish our package on PyPI so that other users can install it on their local machines. Note that our example package depends on
scikit-learn and this dependency is explicitly specified in
setup.py file. Therefore, when users install your package using say
pip, the specified dependencies will also be installed.
Now that our source code is structured and contains all the required files for packaging we can go ahead and create the source distribution.
A source distribution — commonly referred to as sdist — is a distribution that contains the
setup.py file along with the source code and data files (as specified in the
You can create the source distribution of the package by running the command given below:
python setup.py sdist
If everything goes to plan should create a
.tar.gz file under the newly created directory
dist. In my case
setuptools also added a
MANIFEST file too.
Note: If by any chance you’ve got a warning similar to
Unknown distribution option: 'install_requires'
you can ignore it for now.
twine is a utility package that is used for publishing Python packages on PyPI.
pip install twine
In order to publish a package on PyPI you have to create an account. You can do so by visiting this link. It’s completely free and to sign up you just need to provide your e-mail address, username, and password.
Finally, we’ll now use
twine in order to upload the created source distribution on PyPI.
twine upload dist/*
You will be prompted to type your username and password and your package will be finally made available on PyPI:
twine upload dist/* Uploading distributions to https://upload.pypi.org/legacy/ Enter your username: YOUR_USER_NAME Enter your password: YOUR_PASSWORD Uploading test_pypi_medium-0.6.tar.gz 100%|██████████████████████████████████████████████████████████████| 3.49k/3.49k [00:01<00:00, 2.17kB/s]View at: https://pypi.org/project/test-pypi-medium/0.6/
Voila! Our example package is now available on PyPI.
Now let’s verify that our package works as expected. As we already mentioned, the default source index of
pip is PyPI. Therefore, our package can be installed directly from
pip. To do so, run
pip install test-pypi-medium==0.6
The package should be successfully installed on your local machine. If you inspect the output you’ll also see that
scikit-learn is also installed since it is a dependency that we also specified while we were packaging our source code.
Finally, we can verify that the package works as expected:
from test_pypi_medium.example import custom_sklearn