DOC: Add f2py distribution guide for meson-python by HaoZeke · Pull Request #30968 · numpy/numpy

HaoZeke · 2026-03-08T17:16:59Z

Add documentation explaining how to package and distribute F2PY-wrapped Fortran extensions using meson-python as the PEP 517 build backend. Covers pyproject.toml setup, meson.build configuration, building wheels, compiler customization, and linking external dependencies.

Closes #25199.

rgommers

Thanks @HaoZeke! I did a very quick first pass here. Overall looks good & useful

rgommers · 2026-03-09T12:20:18Z

+
+You need:
+
+* A Fortran compiler (``gfortran``, ``ifort``, ``ifx``, ``flang-new``, etc.)


Actually you don't. SciPy now happily builds (with the _no-fortran build option) without any Fortran compiler, but still using f2py to generate code for BLAS/LAPACK bindings. So maybe put this after "A C compiler" and add "if you use any Fortran code in your package".

rgommers · 2026-03-09T12:23:19Z

+
+.. code-block:: bash
+
+   pip wheel . --no-deps -w dist/


I'd remove this, build is strictly better in every sense.

rgommers · 2026-03-09T12:24:08Z

+.. code-block:: bash
+
+   pip install build
+   python -m build


I suggest:

# If you don't yet have `pypa/build` installed: `pip install build` python -m build --wheel

rgommers · 2026-03-09T12:26:10Z

+Customizing the Fortran compiler
+================================
+
+``meson-python`` delegates compiler selection to ``meson``. Set the ``FC``


I'd insert:

By default, ``meson`` will choose the first Fortran compiler it finds on the PATH. If you want more control over Fortran compiler selection, set ...

rgommers · 2026-03-09T12:28:29Z

+detection logic. See the `Meson dependency documentation
+<https://mesonbuild.com/Dependencies.html>`_ for details.
+
+Differences from the ``scikit-build`` workflow


Can we refer only to scikit-build-core please? scikit-build is legacy and best ignored by now. Ah, which you say below. I'd remove it completely. scikit-build-core is not legacy, it's a good build backend - so let's mention the modern one, not the ancient one.

mattip

Cool, thanks. Some clarification comments, but I admit things would be clearer to me if I just tried it out.

mattip · 2026-03-15T17:03:51Z

Is there an open issue for refactoring the f2py documentation structure? After this PR it looks like this

The weirdly formatted "1 Migrating to meson" appears twice
This PR has the accurate title of "Distributing F2PY extensions with meson-python", but the other sections have "Using ..." which is too general. The "Using via scikit-build" should be "Distributing F2PY extensions with scikit-build" and the other ones should be "Building an extension with meson" and "Building an extension with CMake".
I didn't do a deep dive, but the three (including this one) meson pages presents much of the same information in different ways.

It would be good to build a story about the same fortran module being wrapped in the different ways, and have the guides build on one another.

Should I move this comment into a new issue?

HaoZeke · 2026-03-15T18:11:04Z

Is there an open issue for refactoring the f2py documentation structure? After this PR it looks like this

The weirdly formatted "1 Migrating to meson" appears twice

This PR has the accurate title of "Distributing F2PY extensions with meson-python", but the other sections have "Using ..." which is too general. The "Using via scikit-build" should be "Distributing F2PY extensions with scikit-build" and the other ones should be "Building an extension with meson" and "Building an extension with CMake".

I didn't do a deep dive, but the three (including this one) meson pages presents much of the same information in different ways.

It would be good to build a story about the same fortran module being wrapped in the different ways, and have the guides build on one another.

Should I move this comment into a new issue?

I'm up for refactoring it a bit in this PR itself, if it's not too much review burden

mattip · 2026-03-15T18:39:58Z

Yes please. Or you can open a new PR, I think this is ready, pending @rgommers review

rgommers · 2026-03-15T19:02:43Z

Okay having a look now

Address mattip's review on numpy#30968: - "Using via meson" -> "Building an extension with meson" - "Using via cmake" -> "Building an extension with CMake" - "Using via scikit-build" -> "Distributing F2PY extensions with scikit-build-core" - "1 Migrating to meson" -> "Migrating from distutils to meson" (fix heading level from subsection to title, remove "1" prefix) - Remove duplicate toctree entry for distutils-to-meson from f2py/index.rst (was causing it to appear twice in the sidebar)

rgommers

A few detail-focused comments, this is pretty close though - happy to see this merged in its current form.

Add a complete tutorial for packaging F2PY extensions as installable Python distributions using meson-python as the PEP 517 build backend. Covers project layout, pyproject.toml configuration, meson.build with dependency('numpy'), wheel building via pypa/build, editable installs, Fortran compiler selection, BLAS/LAPACK dependencies, and comparison with scikit-build-core. Also fixes the pandas intersphinx URL (moved to pandas.pydata.org/docs). Closes numpy#25199 Co-authored-by: Ralf Gommers <[email protected]> Co-authored-by: Matti Picus <[email protected]>

HaoZeke · 2026-03-15T20:55:53Z

Thanks @rgommers and @mattip, I think this is ready to go in now, have a cleanup for the nav stuff and some other things incoming based on this.

mattip · 2026-03-16T07:34:01Z

Thanks @HaoZeke

mattip · 2026-03-16T07:39:05Z

    'imageio': ('https://imageio.readthedocs.io/en/stable', None),
    'skimage': ('https://scikit-image.org/docs/stable', None),
-    'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
+    'pandas': ('https://pandas.pydata.org/docs', None),


Heh, you fixed pandas doc refactoring.

HaoZeke requested a review from melissawm March 8, 2026 17:17

HaoZeke added 04 - Documentation component: numpy.f2py labels Mar 8, 2026

HaoZeke force-pushed the doc/f2py-distribution-guide branch 2 times, most recently from 7d318ca to 38fb8dd Compare March 8, 2026 20:23

rgommers reviewed Mar 9, 2026

View reviewed changes

HaoZeke force-pushed the doc/f2py-distribution-guide branch 2 times, most recently from a3f89d8 to cde5986 Compare March 15, 2026 00:59

mattip reviewed Mar 15, 2026

View reviewed changes

Comment thread doc/source/f2py/code/pyproj_mesonpy.toml Outdated

Comment thread doc/source/f2py/buildtools/meson-python.rst

Comment thread doc/source/f2py/buildtools/meson-python.rst

Comment thread doc/source/f2py/buildtools/meson-python.rst Outdated

HaoZeke force-pushed the doc/f2py-distribution-guide branch from cde5986 to 586c866 Compare March 15, 2026 10:47

HaoZeke requested a review from rgommers March 15, 2026 18:57

rgommers reviewed Mar 15, 2026

View reviewed changes

HaoZeke force-pushed the doc/f2py-distribution-guide branch from f2006f1 to 946ce6c Compare March 15, 2026 20:14

HaoZeke force-pushed the doc/f2py-distribution-guide branch from 946ce6c to 97c2ec9 Compare March 15, 2026 20:19

HaoZeke requested review from mattip and rgommers March 15, 2026 20:55

mattip merged commit 44a3e6c into numpy:main Mar 16, 2026
73 checks passed

mattip reviewed Mar 16, 2026

View reviewed changes

HaoZeke deleted the doc/f2py-distribution-guide branch March 16, 2026 14:46


		You need:

		* A Fortran compiler (``gfortran``, ``ifort``, ``ifx``, ``flang-new``, etc.)

Conversation

HaoZeke commented Mar 8, 2026

Uh oh!

rgommers left a comment

Choose a reason for hiding this comment

Uh oh!

rgommers Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

rgommers Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

rgommers Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rgommers Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rgommers Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

mattip left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mattip commented Mar 15, 2026

Uh oh!

HaoZeke commented Mar 15, 2026

Uh oh!

mattip commented Mar 15, 2026

Uh oh!

rgommers commented Mar 15, 2026

Uh oh!

rgommers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

HaoZeke commented Mar 15, 2026

Uh oh!

Uh oh!

mattip commented Mar 16, 2026

Uh oh!

mattip Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants