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.220s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.198s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
buildapi
✓ from flit_core import buildapi
flit_core.buildapi is the *only* public interface, exposed for PEP 517 build backend integration. Direct user-level imports for typical application logic are uncommon; most users interact via the `flit` CLI or `python -m build`.
Flit-core is a build backend, not typically imported directly by end-user applications for their runtime logic. Its primary 'usage' is being declared in a project's `pyproject.toml` file to specify how the package should be built. The example shows the standard `pyproject.toml` configuration for using `flit-core`.
# This is typically found in pyproject.toml, not direct Python code.
# A project using flit-core as its build backend would declare it like this:
# pyproject.toml
# [build-system]
# requires = ["flit_core>=3.2,<4"]
# build-backend = "flit_core.buildapi"
print("flit-core is primarily a build backend. ")
print("Its usage is declared in pyproject.toml and invoked by build tools.")
print("For creating and publishing a package, install 'flit' (pip install flit).")
print("Then run 'flit init' and 'flit publish'.")
flit --version
Debug
Known issues
breakingUpcoming Flit 4.0 (which uses flit-core) plans to remove support for old-style metadata in `[tool.flit.metadata]` in favor of the standardized `[project]` table in `pyproject.toml`.fixMigrate your project's metadata from `[tool.flit.metadata]` to the `[project]` table in `pyproject.toml`.
affects: Flit 4.0 onwards (affects projects built with Flit)
breakingIn Flit 4.0, the `flit build` command will no longer default to using information from Git to determine source distribution contents. This changes how `sdist` includes are determined by default, to be more explicit.fixExplicitly define `sdist` inclusions/exclusions in `pyproject.toml` under `[tool.flit.sdist]`, or use `python -m build` which already bypasses this implicit Git integration.
affects: Flit 4.0 onwards (affects projects built with Flit CLI)
gotchaFlit-core provides a PEP 517 build backend and is an internal component. Direct programmatic interaction for general packaging tasks is usually done via the `flit` CLI or standard tools like `python -m build` and `twine`.fixFor packaging projects, install `flit` (`pip install flit`) and use its CLI commands (`flit init`, `flit build`, `flit publish`), or use `python -m build` combined with `twine upload` for a more universal packaging workflow.
affects: All versions
gotchaFlit-core requires Python 3. While older `flit-core` versions supported Python 3.4+, current versions (like 3.12.0) explicitly require `Python >=3.6`. Ensure your environment meets this minimum requirement.fixEnsure your development and build environments use Python 3.6 or newer.
affects: All versions (specific minimum Python version varies by flit-core version)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flit_core'
This error occurs when the Python environment where a build or installation is being attempted cannot locate the `flit_core` package, often due to build isolation issues or an incomplete environment setup where a tool expects `flit_core` to be directly importable.
fixEnsure `flit_core` is installed in the environment or that the build process correctly handles build isolation. If building a project, `pip install .` or `python -m build` should automatically manage build backend dependencies. For specific scenarios like `conda build`, explicitly add `flit-core` to build dependencies.
ModuleNotFoundError: No module named 'flit_core.dummy'
This specific module not found error arises when Flit attempts to extract the package version by importing the module (due to static analysis failure) and encounters a relative import within the `__init__.py` file of the package being built, which fails during this fallback import.
fixRefactor the project's `__init__.py` to avoid relative imports if Flit needs to import it to determine the version. Alternatively, ensure the version can be determined through static analysis (e.g., by defining `__version__` directly without complex logic or imports).
ERROR: Could not find a version that satisfies the requirement flit_core<4,>=3.9.0 (from versions: none). ERROR: No matching distribution found for flit_core<4,>=3.9.0
This error typically indicates that `pip` is unable to find a compatible `flit-core` distribution that matches the version requirements specified by a dependent package, often in offline installation scenarios, due to a misconfigured package index, or when a pre-downloaded wheel is not located correctly.
fixVerify network connectivity if installing online, check PyPI mirrors or internal package indexes, or ensure that the correct `flit_core` wheel file (matching the required version range and platform) is available in the specified `--find-links` directory for offline installations. Using `--no-build-isolation` might sometimes circumvent the issue if the host environment already has a suitable `flit-core` version.
Invalid pyproject.toml: TOML parse error at line X, column Y | backend-path = "." | ^^^ invalid type: string ".", expected a sequence.
This error occurs because the `backend-path` field in `pyproject.toml` (specifically for `flit-core >= 3`) expects a list of paths, even if there's only one, but it was provided as a string.
fixChange the `backend-path` entry in your `pyproject.toml` from a string to a list. For example, change `backend-path = "."` to `backend-path = ["."]`.
FileNotFoundError: [Errno 2] No such file or directory: 'setup.py'
This error happens when an external tool or a build environment expects a `setup.py` file, but the project is configured to use `flit-core` as its build backend, which relies solely on `pyproject.toml` for metadata and build instructions and does not generate a `setup.py` by default.
fixEnsure the build command or tool explicitly recognizes `pyproject.toml` as the build system (e.g., `pip install .` or `python -m build`). If using an older tool that strictly requires `setup.py`, consider if `flit` is the appropriate build backend or explore options to generate a `setup.py` if available (though this goes against the spirit of Flit's simplicity).
Upgrade
Version history
4.0.2latest on PyPI · released Aug 4, 2026
Audit
Dependencies
pythonrequiredCore dependency for Python package functionality.