This tutorial uses a simple project named ``example_pkg``. If you are unfamiliar

with Python's modules and :term:`import packages <import package>`, take a few

minutes to read over the `Python documentation for packages and modules`_. Even if you already have a project that you want to package up, we recommend following this tutorial as-is using this example package and then trying with your own package.

To create this project locally, create the following file structure:

code in there:

.. code-block:: python

This is just so that you can verify that it installed correctly later in this

about your package (such as the name and version) as well as which code files

to include.

Open :file:`setup.py` and enter the following content. You **should** update the package name to include your username (for example, ``example-pkg-theacodes``. You can personalize the other values if you'd like:

.. code-block:: python

:func:`setup` takes several arguments. This example package uses a relatively

minimal set:

- ``name`` is the *distribution name* of your package. This can be any name as long as only

contains letters, numbers, ``_`` , and ``-``. It also must not already

taken on pypi.org. **Be sure to update this with your username,** as this ensures you won't run into any name collisions when you upload the package.

- ``version`` is the package version see :pep:`440` for more details on

versions.

- ``author`` and ``author_email`` are used to identify the author of the

will just be a link to GitHub, GitLab, Bitbucket, or similar code hosting

service.

- ``packages`` is a list of all Python :term:`import packages <Import

Package>` that should be included in the :term:`distribution package`.

Instead of listing each package manually, we can use :func:`find_packages`

to automatically discover all packages and subpackages. In this case, the

list of packages will be `example_pkg` as that's the only package present.

.. code-block:: text

.. note:: If you run into trouble here, please copy the output and file an issue

over on `packaging problems`_ and we'll do our best to help you!

Once uploaded your package should be viewable on TestPyPI, for example,

https://test.pypi.org/project/example-pkg-your-username

Installing your newly uploaded package

.. code-block:: bash

Make sure to specify your username in the package name!

pip should install the package from Test PyPI and the output should look

something like this:

.. code-block:: text

You can test that it was installed correctly by importing the module and

referencing the ``name`` property you put in :file:`__init__.py` earlier.

And then import the module and print out the ``name`` property. This should be

the same regardless of what you name you gave your :term:`distribution package`

in :file:`setup.py` (in this case, ``example-pkg-your-username``) because your :term:`import package` is ``example_pkg``.

.. code-block:: python

✨ 🍰 ✨

Keep in mind that this tutorial showed you how to upload your package to Test

PyPI, which isn't a permanent storage. The Test system occasionally deletes

packages and accounts. If you want to upload your package to the real Python

Package Index you can do it by registering an account on https://pypi.org and

following the same instructions, however, use ``twine upload dist/*`` to upload