Install & Compatibility
Where this runs
tested against v4.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 26.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.6s · import 0.000s · 27MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
flit
✓ Flit is primarily a command-line tool. Direct Python imports for typical packaging tasks are not common.
Users interact with Flit via its command-line interface (e.g., `flit init`, `flit build`, `flit publish`). The `flit_core` package provides the PEP 517 build backend, with its public API at `flit_core.buildapi`, which is generally used by build frontends, not directly by end-user Python code.
To get started with Flit, first create your Python module or package with a `__version__` attribute. Then, navigate to your project's root directory and run `flit init` to generate a `pyproject.toml` file. This file will contain your package's metadata. You can then build your distribution files using `flit build` and publish them to PyPI with `flit publish`.
# Create a directory for your package, e.g., 'my_package'
# Inside 'my_package', create 'my_module.py' or a package directory 'my_module/__init__.py'
# my_module/__init__.py (or my_module.py)
"""An amazing sample package!"""
__version__ = "0.1.0"
def greet(name):
return f"Hello, {name}!"
# In the root of your package directory (e.g., 'my_package')
# 1. Initialize Flit (creates pyproject.toml)
# flit init
# This would be the content of the generated pyproject.toml (adjust details):
# [build-system]
# requires = ["flit_core >=3.2,<4"]
# build-backend = "flit_core.buildapi"
# [project]
# name = "my-module-name"
# authors = [{name = "Your Name", email = "your.email@example.com"}]
# dynamic = ["version", "description"]
# classifiers = [
# "Programming Language :: Python :: 3",
# "License :: OSI Approved :: MIT License",
# "Operating System :: OS Independent",
# ]
# requires-python = ">=3.8"
# 2. Build the package (creates .whl and .tar.gz in 'dist/')
# flit build
# 3. Publish to PyPI (requires PyPI credentials setup)
# flit publish --repository pypi
# Example of using the installed package locally:
# pip install --no-index --find-links=./dist my-module-name
# import my_module
# print(my_module.greet("Flit User"))
flit --version
Debug
Known issues
breakingFlit 3.0 removed support for the older `flit.ini` configuration file format. Projects must now use `pyproject.toml` for all metadata.fixConvert `flit.ini` to `pyproject.toml` by running `python3 -m flit.tomlify` in your project directory. Ensure `[build-system]` and `[project]` tables are correctly configured according to PEP 621.
affects: >=3.0
breakingThe `flit_core` build backend, which Flit uses, now explicitly requires Python 3. This means that while Flit can package Python 2 modules, it must be run on a Python 3 interpreter.fixAlways install and run Flit using a Python 3 environment (e.g., `python3 -m pip install flit`). Ensure your project's `pyproject.toml` specifies `requires-python` appropriately.
affects: flit_core >= 3.x
deprecatedIn Flit 3.5, the default behavior of `flit build` and `flit publish` changed; they no longer generate a `setup.py` file in the sdist by default. This makes sdists only compatible with tools supporting PEP 517.fixIf you need to support older installers that do not support PEP 517 and require a `setup.py`, you can explicitly include it during `flit build` or `flit publish` (check documentation for specific flags if needed, though typically `--sdist-include-setup-py` was removed in favor of `pyproject.toml` configuration).
affects: >=3.5
gotchaFlit is designed for pure Python packages without complex build steps (e.g., C extensions, bundled Javascript). If your project requires compilation or other build processes, Flit may not be the most suitable tool.fixFor projects with complex build requirements, consider alternative tools like Setuptools or Hatchling, which are designed to handle such scenarios.
affects: All versions
gotchaFlit does not manage your project's dependencies directly; you must declare them in `pyproject.toml` manually. Tools like Poetry or Pipenv offer integrated dependency management.fixEnsure all external package dependencies are accurately listed in the `[project.dependencies]` section of your `pyproject.toml`.
affects: All versions
Upgrade
Version history
4.0.2latest on PyPI · released Aug 4, 2026
Audit
Dependencies
flit_corerequiredProvides the PEP 517 build backend for Flit. It is automatically installed as a dependency.