Flit-core

3.12.0 verified Tue May 12 auth: no python install: verified

Flit-core provides a PEP 517 compliant build backend, encapsulating the core distribution-building logic for projects that use Flit for packaging. It is an essential dependency for the user-facing `flit` tool, enabling the creation of wheels and source distributions. The current version is 3.12.0, released on March 25, 2025, and maintains a fairly active release cadence with multiple updates throughout the year.

pip install flit-core

Common errors

error ModuleNotFoundError: No module named 'flit_core' ↓

cause 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.

fix

Ensure 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.

error ModuleNotFoundError: No module named 'flit_core.dummy' ↓

cause 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.

fix

Refactor 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 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 ↓

cause 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.

fix

Verify 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.

error Invalid pyproject.toml: TOML parse error at line X, column Y | backend-path = "." | ^^^ invalid type: string ".", expected a sequence. ↓

cause 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.

fix

Change the backend-path entry in your pyproject.toml from a string to a list. For example, change backend-path = "." to backend-path = ["."].

error FileNotFoundError: [Errno 2] No such file or directory: 'setup.py' ↓

cause 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.

fix

Ensure 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).

Warnings

breaking Upcoming 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`. ↓

fix Migrate your project's metadata from `[tool.flit.metadata]` to the `[project]` table in `pyproject.toml`.

breaking In 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. ↓

fix Explicitly define `sdist` inclusions/exclusions in `pyproject.toml` under `[tool.flit.sdist]`, or use `python -m build` which already bypasses this implicit Git integration.

gotcha Flit-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`. ↓

fix For 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.

gotcha Flit-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. ↓

fix Ensure your development and build environments use Python 3.6 or newer.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.19s 18.1M

3.10 alpine (musl) - - 0.21s 18.1M

3.10 slim (glibc) wheel 1.5s 0.13s 19M

3.10 slim (glibc) - - 0.13s 19M

3.11 alpine (musl) wheel - 0.29s 20.0M

3.11 alpine (musl) - - 0.33s 20.0M

3.11 slim (glibc) wheel 1.5s 0.24s 21M

3.11 slim (glibc) - - 0.25s 21M

3.12 alpine (musl) wheel - 0.24s 11.9M

3.12 alpine (musl) - - 0.29s 11.9M

3.12 slim (glibc) wheel 1.4s 0.24s 12M

3.12 slim (glibc) - - 0.25s 12M

3.13 alpine (musl) wheel - 0.22s 11.6M

3.13 alpine (musl) - - 0.24s 11.5M

3.13 slim (glibc) wheel 1.5s 0.21s 12M

3.13 slim (glibc) - - 0.23s 12M

3.9 alpine (musl) wheel - 0.17s 17.6M

3.9 alpine (musl) - - 0.21s 17.6M

3.9 slim (glibc) wheel 1.8s 0.15s 18M

3.9 slim (glibc) - - 0.15s 18M

Imports

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`.

Quickstart last tested: 2026-04-24

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'.")