meson-python is a Python build backend (PEP 517) that integrates the Meson build system for Python packages. It is particularly well-suited for projects that include extension modules written in compiled languages such as C, C++, Cython, Fortran, Pythran, or Rust. The library is actively maintained, with version 0.19.0 currently available, and new releases occurring every few months to introduce features and address compatibility.
Install & Compatibility
Where this runs
tested against v0.19.0 · 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.960 runs
installs and imports cleanly · install 0.0s · import 0.000s · 78.5MB
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 2.5s · import 0.000s · 28MB
53MB installed
● package 53MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mesonpy
✓ # Defined in pyproject.toml
[build-system]
build-backend = 'mesonpy'
meson-python is a build backend and is not typically imported into Python code. Its functionality is invoked by build frontends (like pip or build) via the 'build-backend' entry in pyproject.toml.
This quickstart demonstrates how to set up a minimal Python project using `meson-python` as the build backend. It involves creating a `pyproject.toml` to declare `mesonpy` as the backend and a `meson.build` file to define the build logic. The example then shows how to build a wheel distribution and optionally install and test it.
mkdir my_project
cd my_project
# Create pyproject.toml
cat <<EOL > pyproject.toml
[build-system]
requires = ["meson-python", "meson", "ninja"]
build-backend = "mesonpy"
[project]
name = "my_example_package"
version = "0.1.0"
EOL
# Create meson.build
cat <<EOL > meson.build
project('my_example_package', 'python', version: '0.1.0')
python = import('python').find_installation(pure: false)
python.install_sources(
'src/my_example_package/__init__.py',
subdir: 'my_example_package'
)
EOL
# Create a simple Python source file
mkdir -p src/my_example_package
cat <<EOL > src/my_example_package/__init__.py
def greet():
return "Hello from my_example_package!"
EOL
# Build the package (e.g., a wheel)
python -m build --wheel
# Install and test (optional)
pip install dist/*.whl
python -c "from my_example_package import greet; print(greet())"
Debug
Known issues
breakingPython 3.7 support was dropped in meson-python 0.18.0, and Python 3.8 support was dropped in 0.19.0. Projects using these older Python versions will need to upgrade to at least Python 3.9.fixUpgrade your project's Python interpreter to 3.9 or newer.
affects: >=0.18.0
breakingThe minimum required Meson version was bumped to 0.64.0 in meson-python 0.18.0, and Meson 1.2.3 or later is required for Python 3.12+ in meson-python 0.15.0.fixEnsure that Meson version 0.64.0 or newer (or 1.2.3+ for Python 3.12+) is installed in your build environment.
affects: >=0.15.0, >=0.18.0
gotchaMeson's `install_data()` function installs non-package data files to a platform-specific location, making them difficult to reliably find at runtime after wheel installation.fixFor data files needed at runtime, include them within your Python package alongside the code and access them using `importlib.resources` (or the `importlib-resources` backport for older Python versions).
affects: All
gotchaPassing native build options to Meson via `pip` or `build` can be complex due to the layers of abstraction introduced by the PEP 517 backend. Full control over Meson flags might be hindered.fixWhile some options can be passed via environment variables or specific build frontend flags, for fine-grained control or complex native configurations, consider an explicit `meson setup` step before invoking the Python build frontend, or consult `meson-python` documentation on passing build config settings.
affects: All
gotchaChanges in `os.path.isabs` semantics in Python 3.13 have been reported to break Meson's path detection on Windows, which could lead to build failures for projects using `meson-python`.fixMonitor `meson-python` and Meson project releases for compatibility fixes with Python 3.13. If encountering issues, consider using an earlier Python version until a fix is available.
affects: Potentially future versions of Python 3.13+
Audit
Dependencies
mesonrequiredRequired build system that meson-python integrates with.
ninjarequiredDefault high-performance build tool used by Meson.
pythonrequiredRequires Python 3.9 or newer. Python 3.8 support was dropped in 0.19.0.
pyproject-metadatarequiredMinimum required version has been bumped multiple times for PEP 639 support and other features.