Using F2PY#

This page contains a reference to all command-line options for the f2py command, as well as a reference to internal functions of the numpy.f2py module.

Using f2py as a command-line tool#

When used as a command-line tool, f2py has three major modes, distinguished by the usage of -c and -h switches.

1. Signature file generation#

To scan Fortran sources and generate a signature file, use

f2py -h <filename.pyf> <options> <fortran files>   \
  [[ only: <fortran functions>  : ]                \
    [ skip: <fortran functions>  : ]]...           \
  [<fortran files> ...]

If <filename.pyf> is specified as stdout, then signatures are written to standard output instead of a file.

Among other options (see below), the following can be used in this mode:

--overwrite-signature

Overwrites an existing signature file.

2. Extension module construction#

To construct an extension module, use

f2py -m <modulename> <options> <fortran files>   \
  [[ only: <fortran functions>  : ]              \
    [ skip: <fortran functions>  : ]]...          \
  [<fortran files> ...]

The constructed extension module is saved as <modulename>module.c to the current directory.

Here <fortran files> may also contain signature files. Among other options (see below), the following options can be used in this mode:

--debug-capi

Adds debugging hooks to the extension module. When using this extension module, various diagnostic information about the wrapper is written to the standard output, for example, the values of variables, the steps taken, etc.

-include'<includefile>'

Add a CPP #include statement to the extension module source. <includefile> should be given in one of the following forms

"filename.ext"
<filename.ext>

The include statement is inserted just before the wrapper functions. This feature enables using arbitrary C functions (defined in <includefile>) in F2PY generated wrappers.

Note

This option is deprecated. Use usercode statement to specify C code snippets directly in signature files.

--[no-]wrap-functions

Create Fortran subroutine wrappers to Fortran functions. --wrap-functions is default because it ensures maximum portability and compiler independence.

--[no-]freethreading-compatible

Create a module that declares it does or doesnt require the GIL. The default is --no-freethreading-compatible for backwards compatibility. Inspect the fortran code you are wrapping for thread safety issues before passing --freethreading-compatible, as f2py does not analyze fortran code for thread safety issues.

--include-paths "<path1>:<path2>..."

Search include files from given directories.

Note

The paths are to be separated by the correct operating system separator pathsep, that is : on Linux / MacOS and ; on Windows. In CMake this corresponds to using $<SEMICOLON>.

3. Building a module#

To build an extension module, use

f2py -c <options> <fortran files>       \
  [[ only: <fortran functions>  : ]     \
    [ skip: <fortran functions>  : ]]... \
  [ <fortran/c source files> ] [ <.o, .a, .so files> ]

If <fortran files> contains a signature file, then the source for an extension module is constructed, all Fortran and C sources are compiled, and finally all object and library files are linked to the extension module <modulename>.so which is saved into the current directory.

If <fortran files> does not contain a signature file, then an extension module is constructed by scanning all Fortran source codes for routine signatures, before proceeding to build the extension module.

Among other options (see below) and options described for previous modes, the following can be used.

Common build flags:

--backend <backend_type>

Legacy option, only meson is supported.

--f77flags=<string>

Specify F77 compiler flags

--f90flags=<string>

Specify F90 compiler flags

--debug

Compile with debugging information

-l<libname>

Use the library <libname> when linking.

-D<macro>[=<defn=1>]

Define macro <macro> as <defn>.

-U<macro>

Define macro <macro>

-I<dir>

Append directory <dir> to the list of directories searched for include files.

-L<dir>

Add directory <dir> to the list of directories to be searched for -l.

--dep <dependency>

Specify a meson dependency for the module. This may be passed multiple times for multiple dependencies. Dependencies are stored in a list for further processing. Example: --dep lapack --dep scalapack This will identify lapack and scalapack as dependencies and remove them from argv, leaving a dependencies list containing [lapack, scalapack].

f2py -c -m fib1 fib1.f

f2py -m fib1 fib1.f -h fib1.pyf
f2py -c fib1.pyf fib1.f

When building an extension module, a combination of the following macros may be required for non-gcc Fortran compilers:

-DPREPEND_FORTRAN
-DNO_APPEND_FORTRAN
-DUPPERCASE_FORTRAN

To test the performance of F2PY generated interfaces, use -DF2PY_REPORT_ATEXIT. Then a report of various timings is printed out at the exit of Python. This feature may not work on all platforms, and currently only Linux is supported.

To see whether F2PY generated interface performs copies of array arguments, use -DF2PY_REPORT_ON_ARRAY_COPY=<int>. When the size of an array argument is larger than <int>, a message about the copying is sent to stderr.

Other options#

-m <modulename>

Name of an extension module. Default is untitled.

--[no-]lower

Do [not] lower the cases in <fortran files>. By default, --lower is assumed with -h switch, and --no-lower without the -h switch.

-include<header>

Writes additional headers in the C wrapper, can be passed multiple times, generates #include <header> each time. Note that this is meant to be passed in single quotes and without spaces, for example '-include<stdbool.h>'

--build-dir <dirname>

All F2PY generated files are created in <dirname>. Default is tempfile.mkdtemp().

--f2cmap <filename>

Load Fortran-to-C KIND specifications from the given file.

--quiet

Run quietly.

--verbose

Run with extra verbosity.

--skip-empty-wrappers

Do not generate wrapper files unless required by the inputs. This is a backwards compatibility flag to restore pre 1.22.4 behavior.

-v

Print the F2PY version and exit.

Execute f2py without any options to get an up-to-date list of available options.

Python module numpy.f2py#

When using numpy.f2py as a module, the following functions can be invoked.

Fortran to Python Interface Generator.

Copyright 1999 2011 Pearu Peterson all rights reserved. Copyright 2011 present NumPy Developers. Permission to use, modify, and distribute this software is given under the terms of the NumPy License.

NO WARRANTY IS EXPRESSED OR IMPLIED. USE AT YOUR OWN RISK.

numpy.f2py.get_include()[source]#

Return the directory that contains the fortranobject.c and .h files.

Python extension modules built with f2py-generated code need to use fortranobject.c as a source file, and include the fortranobject.h header. This function can be used to obtain the directory containing both of these files.

Returns:

include_pathstr

Absolute path to the directory containing fortranobject.c and fortranobject.h.

See also

numpy.get_include

function that returns the numpy include directory

Notes

New in version 1.21.1.

Unless the build system you are using has specific support for f2py, building a Python extension using a .pyf signature file is a two-step process. For a module mymod:

• Step 1: run python -m numpy.f2py mymod.pyf --quiet. This generates mymodmodule.c and (if needed) mymod-f2pywrappers.f files next to mymod.pyf.

• Step 2: build your Python extension module. This requires the following source files:

  • mymodmodule.c

  • mymod-f2pywrappers.f (if it was generated in Step 1)

  • fortranobject.c

numpy.f2py.run_main(comline_list)[source]#

Equivalent to running:

f2py <args>

where <args>=string.join(<list>,' '), but in Python. Unless -h is used, this function returns a dictionary containing information on generated modules and their dependencies on source files.

You cannot build extension modules with this function, that is, using -c is not allowed. Use the compile command instead.

Examples

Try it in your browser!

The command f2py -m scalar scalar.f can be executed from Python as follows.

>>> import numpy.f2py
>>> r = numpy.f2py.run_main(['-m','scalar','doc/source/f2py/scalar.f'])
Reading fortran codes...
        Reading file 'doc/source/f2py/scalar.f' (format:fix,strict)
Post-processing...
        Block: scalar
                        Block: FOO
Building modules...
        Building module "scalar"...
        Wrote C/API module "scalar" to file "./scalarmodule.c"
>>> print(r)
{'scalar': {'h': ['/home/users/pearu/src_cvs/f2py/src/fortranobject.h'],
	 'csrc': ['./scalarmodule.c', 
                  '/home/users/pearu/src_cvs/f2py/src/fortranobject.c']}}

Go BackOpen In Tab

Building with Meson (Examples)#

Using f2py with Meson#

Meson is a modern build system recommended for building Python extension modules, especially starting with Python 3.12 and NumPy 2.x. Meson provides a robust and maintainable way to build Fortran extensions with f2py.

To build a Fortran extension using f2py and Meson, you can use Mesons custom_target to invoke f2py and generate the extension module. The following minimal example demonstrates how to do this:

This example shows how to build the add extension from the add.f and add.pyf files described in the F2PY examples (note that you do not always need a .pyf file: in many cases f2py can figure out the annotations by itself).

Project layout:

f2py_examples/
  meson.build
  add.f
  add.pyf (optional)
  __init__.py  (can be empty)

Example meson.build:

project('f2py_examples', 'fortran')

py = import('python').find_installation()

# List your Fortran source files
sources = files('add.pyf', 'add.f')

# Build the extension by invoking f2py via a custom target
add_mod = custom_target(
  'add_extension',
  input: sources,
  output: ['add' + py.extension_suffix()],
  command: [
    py.full_path(), '-m', 'numpy.f2py',
    '-c', 'add.pyf', 'add.f',
    '-m', 'add'
  ],
  build_by_default: true
)

# Install into site-packages under the f2py_examples package
install_subdir('.', install_dir: join_paths(py.site_packages_dir(), 'f2py_examples'),
               strip_directory: false,
               exclude_files: ['meson.build'])

# Also install the built extension (place it beside __init__.py)
install_data(add_mod, install_dir: join_paths(py.site_packages_dir(), 'f2py_examples'))

For more details and advanced usage, see the Meson build guide in the user documentation or refer to SciPys Meson build files for real-world examples: scipy/scipy