How to create, upload and install a package for PyPI?

Question

I wrote a little module and I would like to know what are the basic steps to package it in order to upload it to PyPI:

What is the file hierarchy?
How should I name files?
Should I use distutils to create PKG-INFO?
Where should I include my documentation (made with sphinx)?

You might be interested in my [Python Projects article](https://martin-thoma.com/python-projects/) — Martin Thoma, Jan 21 '18 at 19:40

score 12 · Accepted Answer · edited Mar 02 '15 at 17:56

I recommend reading The Hitchhiker's Guide to Packaging. Specifically, you should look at the Quick Start section, which describes how to:

Lay out your project

Describe your project

Create your first release

Register your package with the Python Package Index (PyPI)

Upload your release, then grab your towel and save the Universe!

You should also look at the Current State of Packaging in the Introduction to Packaging section, as this helps untangle some of the confusion surrounding setuptools, distutils, distutils2, and distribute.

Update Re: How to Name Files

The excerpt below is from PEP8, which answers your question about how to name files:

Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

Since module names are mapped to file names, and some file systems are case insensitive and truncate long names, it is important that module names be chosen to be fairly short -- this won't be a problem on Unix, but it may be a problem when the code is transported to older Mac or Windows versions, or DOS.

score 3 · Answer 2 · answered Sep 07 '10 at 12:44

3

an example is always the best way to see how to do:

http://packages.python.org/an_example_pypi_project/

answered Sep 07 '10 at 12:44

Mermoz

14,898
17
60
85

joaquin · Answer 3 · 2014-09-22T17:11:03.920

Maybe this CheeseShopTutorial is of help for you. From there:

Submitting Packages to the Package Index

If you have some Python modules or packages that you would like to share with the Python community, we'd love to have them included in the Python Package Index! First, if you haven't done so, you will want to get your project organized. You might follow the guidelines at ProjectFileAndDirectoryLayout. After that, you'll want to read the Python documentation regarding creating distributions: http://docs.python.org/distutils/index.html.

You can also check Writing a Package in Python by Tarek Ziadé from Tarek's book "Expert Python Programming" where questions about development and distribution are addressed in great detail

score 0 · Answer 4 · answered Apr 15 '16 at 10:01

Matthew Rankin's answer tells you how to organize your project file heirarchy, but I find myself having to look up the commands to execute every time I want to update a project on PyPI. So here they are:

As described on the PyPi site:

Create a setup.py file (here's an example)
Register a username/password with PyPi
Do this: python setup.py sdist python setup.py bdist_wheel python setup.py register twine upload dist/*
Look for your package on the PyPi site: https://pypi.python.org/pypi?%3Aaction=index
On another machine try running: pip install [your package name]

score 0 · Answer 5 · answered Nov 08 '18 at 03:57

Most important thing is prepare your setup.py properly. Then:

setup.py sdist bdist_wheel to generate distribution archives to dist/ folder
twine upload dist/* to upload the archives to PyPi (with your PyPi username/password)

Here is an example of setup.py:

from setuptools import setup, find_packages

with open('README.md') as readme_file:
    README = readme_file.read()

with open('HISTORY.md') as history_file:
    HISTORY = history_file.read()

setup_args = dict(
    name='elastictools',
    version='0.1.2',
    description='Useful tools to work with Elastic stack in Python',
    long_description_content_type="text/markdown",
    long_description=README + '\n\n' + HISTORY,
    license='MIT',
    packages=find_packages(),
    author='Thuc Nguyen',
    author_email='gthuc.nguyen@gmail.com',
    keywords=['Elastic', 'ElasticSearch', 'Elastic Stack', 'Python 3', 'Elastic 6'],
    url='https://github.com/ncthuc/elastictools',
    download_url='https://pypi.org/project/elastictools/'
)

install_requires = [
    'elasticsearch>=6.0.0,<7.0.0',
    'jinja2'
]

if __name__ == '__main__':
    setup(**setup_args, install_requires=install_requires)

You can find more detail tutorial here: https://medium.com/@thucnc/how-to-publish-your-own-python-package-to-pypi-4318868210f9

Super Kai - Kazuya Ito · Answer 6 · 2023-06-07T02:15:05.650

You should follow the tutorial Packaging Python Projects and first, I explain how to create, upload and install a package for TestPyPI and lastly, I explain it for PyPI:

First, create packaging_tutorial folder:

packaging_tutorial/

Then, create a virtual environment in packaging_tutorial folder:

For Linux and Mac:

python -m venv venv && . venv/bin/activate

For Windows:

python -m venv venv && . venv/Scripts/activate

Then, venv folder is created:

packaging_tutorial/
 └-venv/ # Here

Then, upgrade pip:

pip install --upgrade pip

Then, create src/example_package_<YOUR_USERNAME_HERE>/__init__.py(Empty file) and example.py and tests folder(Empty folder) . *Replace <YOUR_USERNAME_HERE> with your username, for example, example_package_superkai in my case:

packaging_tutorial/
 |-src/
 |  └-example_package_<YOUR_USERNAME_HERE>/
 |     ├──__init__.py # Empty file
 |     └──example.py # Here
 |-tests/ # Empty folder
 └-venv/

Then, put the code below to example.py:

def add_one(number):
    return number + 1

Then, create pyproject.toml, LICENSE and README.md:

packaging-tutorial/
 |-src/               # ↓ ↓ ↓ Here ↓ ↓ ↓ 
 |  └-example_package_<YOUR_USERNAME_HERE>/
 |     |-__init__.py
 |     └-example.py
 |-pyproject.toml # Here
 |-README.md # Here
 |-LICENSE # Here
 |-tests/
 └-venv/

Then, put the code below to pyproject.toml. *Replace <YOUR_USERNAME_HERE> with your username:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]               # ↓ ↓ ↓ Here ↓ ↓ ↓
name = "example_package_<YOUR_USERNAME_HERE>"
version = "0.0.1"
authors = [
  { name="Example Author", email="author@example.com" },
]
description = "A small example package"
readme = "README.md"
requires-python = ">=3.7"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
"Homepage" = "https://github.com/pypa/sampleproject"
"Bug Tracker" = "https://github.com/pypa/sampleproject/issues"

Then, put the text below to README.md:

# Example Package

This is a simple example package. You can use
[Github-flavored Markdown](https://guides.github.com/features/mastering-markdown/)
to write your content.

Then, put the text below to LICENSE:

Copyright (c) 2018 The Python Packaging Authority

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Then, upgrade and run build:

pip install --upgrade build && python -m build

Then, dict/...whl and ...tar.gz are created. *<YOUR_USERNAME_HERE> is replaced with your username:

packaging-tutorial/
 |-dist/              # ↓ ↓ ↓ Here ↓ ↓ ↓
 |  ├-example_package_<YOUR_USERNAME_HERE>-0.0.1-py3-none-any.whl
 |  └-example_package_<YOUR_USERNAME_HERE>-0.0.1.tar.gz
 |-src/               # ↑ ↑ ↑ Here ↑ ↑ ↑
 |  └-example_package_<YOUR_USERNAME_HERE>/
 |     |-__init__.py
 |     └-example.py
 |-pyproject.toml
 |-README.md
 |-LICENSE
 |-tests/
 └-venv/

Next, create an account and API token in TestPyPI. *Select Entire account (all projects) for Scope:

Then, an API token is created:

Next, install and upgrade twine:

pip install --upgrade twine

Then, upload example_package_<YOUR_USERNAME_HERE> package to TestPyPI. *Input __token__ for username and the API token for password:

twine upload --repository testpypi dist/*

Then, example_package_<YOUR_USERNAME_HERE> package is uploaded to TestPyPI:

Next, install example_package_<YOUR_USERNAME_HERE> package from TestPyPI:

pip install -i https://test.pypi.org/simple/ example-package-<YOUR_USERNAME_HERE>

Then, you can use example.add_one() from example_package_superkai package(module):

$ python
>>> from example_package_superkai import example           
>>> example.add_one(2)
3

Lastly, how to create, upload and install a package for PyPI is really similar to TestPyPI but there are some differences so for PyPI:

Without --repository testpypi, upload example_package_<YOUR_USERNAME_HERE> package to PyPI:
```
`twine upload dist/*`
```
Without -i https://test.pypi.org/simple/, install example_package_<YOUR_USERNAME_HERE> package from PyPI:
```
pip install example-package-<YOUR_USERNAME_HERE>
```

How to create, upload and install a package for PyPI?

6 Answers6

Update Re: How to Name Files

Linked