flit Build "Missing version or docstring" in pyproject.toml CI
By Daniel Zoghalchali·Latchkey
flit derives version and description from your module’s __version__ and its docstring. If the module lacks either - or [project] does not mark them dynamic - flit_core cannot assemble the metadata and the build fails.
What this error means
A flit build fails with Cannot package module without a version string or Missing docstring in .... The build expects the source module to carry that metadata and stops when it is absent.
Build output
flit_core.common.NoVersionError: Cannot package module without a version string.
Please define a `__version__ = "x.y.z"` in your module.
Diagnose it: is it the build backend or a missing system library?
Python packaging failures in CI split into build-backend configuration problems and missing system headers. The traceback usually points at the backend even when the real cause is an absent -dev package.
Terminal
python -m pip install --upgrade pip build
python -m build --wheel 2>&1 | tail -40
# a compiler error naming a .h file is a system dependency, not a Python one# e.g. "Python.h: No such file" -> python3-dev# "openssl/ssl.h" -> libssl-dev
Common causes
Module missing __version__ or docstring
flit reads __version__ for the version and the top-of-module docstring for the description. A module without them gives flit nothing to record.
Fields not declared dynamic in [project]
When [project] exists, version/description sourced from the module must be listed under dynamic, or flit reports them as missing.
How to fix it
Add __version__ and a module docstring
src/myapp/__init__.py
"""A short one-line description of the package."""
__version__ = "1.0.0"
Mark them dynamic for flit
Tell flit to pull these from the module by listing them as dynamic.
Keep __version__ and a docstring in the package’s top module.
List flit-sourced fields under [project].dynamic.
Run flit build locally after metadata changes.
Frequently asked questions
What causes flit build "Missing version or docstring" in pyproject.toml CI?
There are 2 common causes: module missing __version__ or docstring and fields not declared dynamic in [project]. flit reads __version__ for the version and the top-of-module docstring for the description.
How do I fix flit build "Missing version or docstring" in pyproject.toml CI?
There are 2 fixes depending on which cause you have: add __version__ and a module docstring and mark them dynamic for flit. Work through them in order, since the first is the most common.
What does flit build "Missing version or docstring" in pyproject.toml CI actually mean?
A flit build fails with Cannot package module without a version string or Missing docstring in ....
How do I stop flit build "Missing version or docstring" in pyproject.toml CI happening again?
Keep __version__ and a docstring in the package’s top module. The prevention section lists 3 changes that keep it from recurring.
