Back to Posts
Cardboard box on a wooden table symbolizing the ease of packaging and publishing Python projects with Flit on PyPI, as if shipping a product.

Quick Guide to Publishing Python Packages with Flit

Packaging your Python projects doesn’t have to be a hassle. With Flit, the process of packaging projects and publishing them on PyPI is much simpler. Let me show you how you can publish your package in a few simple steps.

Getting started with Flit

You can install flit in a flash with pip install flit. Once pip has finished installing, you are ready to start publishing your package.

Distributing your Python module with Flit

Imagine you’ve developed a Python module named superpackage. This module could be a single file ( or a directory. The first step in making your module distributable is to ensure its docstring begins with a concise summary of the module’s functionality. Additionally, it’s imperative to include a __version__ in the module:

An amazing package!

__version__ = "0.1"

After installing Flit, navigate to the directory containing your module and execute flit init. This command generates a pyproject.toml configuration file that Flit uses for packaging. The generated file might look something like this:

requires = ["flit_core >=3.2,<4"]
build-backend = "flit_core.buildapi"

name = "superpackage"
authors = [{name = "Arjan"}]
license = {file = "LICENSE"}
classifiers = ["License :: OSI Approved :: MIT License"]
dynamic = ["version", "description"]

If you select a license, a LICENSE file will be created too.

The pyproject.toml file is your go-to for adding additional metadata about your package, such as command-line scripts. For a deeper dive into configuring your pyproject.toml, refer to the documentation’s respective section.

Managing your credentials

Flit provides multiple ways to provide your PyPi credentials. If the keyring library is not installed or doesn’t contain valid credentials, it will search the environment variables. If no credentials are found, it will prompt you for your login when publishing.

Here are the environment variables you can use to add your credentials:

  • FLIT_USERNAME: Your PyPI username or __token__ for token-based uploads.
  • FLIT_PASSWORD: Your password or token.

It is recommended to use tokens, as they can be easily revoked.

Optionally, configure the repository to publish to with:

  • FLIT_INDEX_URL: URL of the package index (default is PyPi, but Flit allows alternative repositories).


Storing a password in an environment variable can lead to accidental leaks. Be cautious, as other scripts and libraries can access these environment variables. This is why it is suggested to use a token, as these can be revoked if they are accidentally leaked. It is also important to treat your token with the same care you do your password, as both allow unfettered access to your account.

Publishing your package

When you’re ready to share your package with the world, Flit streamlines the process with a single command:

flit publish

Upon publication, your package becomes available on PyPI and can be installed by anyone using pip, Python’s package installer. Typically, pip installs packages in the wheel format, though it can also handle source distributions (sdists) by leveraging Flit in a temporary environment.


Flit requires that you follow good project structure and version control management. This means any file that you do not intend to publish must be added to your `.gitignore“ file.

Local development installations

For local development, Flit offers a handy installation option that allows you to work on your package and test it in real-time:

flit install --symlink --python path/to/python

--symlink: will make use of a symbolic link to install, allowing you to edit the library without reinstalling it.

--python /path/to/python: will target a specific Python installation for the installation.

Using this command ensures that any changes you make to your package are immediately reflected, facilitating a smoother development workflow, and enabling you to check that your project is packaged properly before distributing it on PyPI.

Final thoughts

Isn’t it amazing how publishing can be done in just a few simple commands? It really saves you time and effort, right? So, go ahead and share your projects to your heart’s content! For more project tips, check out my post here:

Improve your code with my 3-part code diagnosis framework

Watch my free 30 minutes code diagnosis workshop on how to quickly detect problems in your code and review your code more effectively.

When you sign up, you'll get an email from me regularly with additional free content. You can unsubscribe at any time.

Recent posts