Source Files and Compilation

Cython source file names consist of the name of the module followed by a.pyx extension, for example a module called primes would have a sourcefile named primes.pyx.

Cython code, unlike Python, must be compiled. This happens in two stages:

• A .pyx file is compiled by Cython to a .c file.


• The .c file is compiled by a C compiler to a .so file (or a
  .pyd file on Windows)

Once you have written your .pyx file, there are a couple of ways of turning itinto an extension module.

The following sub-sections describe several ways to build yourextension modules, and how to pass directives to the Cython compiler.

Compiling from the command line

There are two ways of compiling from the command line.

• The cython command takes a .py or .pyx file andcompiles it into a C/C++ file.
• The cythonize command takes a .py or .pyx file andcompiles it into a C/C++ file. It then compiles the C/C++ file intoan extension module which is directly importable from Python.

Compiling with the cython command

One way is to compile it manually with the Cythoncompiler, e.g.:

$ cython primes.pyx

This will produce a file called primes.c, which then needs to becompiled with the C compiler using whatever options are appropriate on yourplatform for generating an extension module. For these options look at theofficial Python documentation.

The other, and probably better, way is to use the setuptools extensionprovided with Cython. The benefit of this method is that it will give theplatform specific compilation options, acting like a stripped down autotools.

Compiling with the cythonize command

Run the cythonize compiler command with your options and list of.pyx files to generate an extension module. For example:

$ cythonize -a -i yourmod.pyx

This creates a yourmod.c file (or yourmod.cpp in C++ mode), compiles it,and puts the resulting extension module (.so or .pyd, depending on yourplatform) next to the source file for direct import (-i builds “in place”).The -a switch additionally produces an annotated html file of the source code.

The cythonize command accepts multiple source files and glob patterns like*/.pyx as argument and also understands the common -j option forrunning multiple parallel build jobs. When called without further options, itwill only translate the source files to .c or .cpp files. Pass the-h flag for a complete list of supported options.

There simpler command line tool cython only invokes the source code translator.

In the case of manual compilation, how to compile your .c files will varydepending on your operating system and compiler. The Python documentation forwriting extension modules should have some details for your system. On a Linuxsystem, for example, it might look similar to this:

$ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing \
      -I/usr/include/python3.5 -o yourmod.so yourmod.c

(gcc will need to have paths to your included header files and pathsto libraries you want to link with.)

After compilation, a yourmod.so (yourmod.pyd for Windows)file is written into the target directoryand your module, yourmod, is available for you to import as with any otherPython module. Note that if you are not relying on cythonize or setuptools,you will not automatically benefit from the platform specific file extensionthat CPython generates for disambiguation, such asyourmod.cpython-35m-x86_64-linux-gnu.so on a regular 64bit Linux installationof CPython 3.5.

Basic setup.py

The setuptools extension provided with Cython allows you to pass .pyx filesdirectly to the Extension constructor in your setup file.

If you have a single Cython file that you want to turn into a compiledextension, say with filename example.pyx the associated setup.pywould be:

from setuptools import setup
from Cython.Build import cythonize
 
setup(
    ext_modules = cythonize("example.pyx")
)

If your build depends directly on Cython in this way,then you may also want to inform pip that Cython is required forsetup.py to execute, following PEP 518<https://www.python.org/dev/peps/pep-0518/&gt;, creating a pyproject.tomlfile containing, at least:

[build-system]
requires = ["setuptools", "wheel", "Cython"]

To understand the setup.py more fully look at the official setuptoolsdocumentation. To compile the extension for use in the current directory use:

$ python setup.py build_ext --inplace

Configuring the C-Build

If you have include files in non-standard places you can pass aninclude_path parameter to cythonize:

from setuptools import setup
from Cython.Build import cythonize
 
setup(
    name="My hello app",
    ext_modules=cythonize("src/*.pyx", include_path=[...]),
)

Often, Python packages that offer a C-level API provide a way to findthe necessary include files, e.g. for NumPy:

include_path = [numpy.get_include()]

Note

Using memoryviews or importing NumPy with import numpy does not mean thatyou have to add the path to NumPy include files. You need to add this path onlyif you use cimport numpy.

Despite this, you will still get warnings like thefollowing from the compiler, because Cython is using a deprecated Numpy API:

.../include/numpy/npy_1_7_deprecated_api.h:15:2: warning: #warning "Using deprecated NumPy API, disable it by " "#defining NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION" [-Wcpp]

For the time being, it is just a warning that you can ignore.

If you need to specify compiler options, libraries to link with or otherlinker options you will need to create Extension instances manually(note that glob syntax can still be used to specify multiple extensionsin one line):

from setuptools import Extension, setup
from Cython.Build import cythonize
 
extensions = [
    Extension("primes", ["primes.pyx"],
        include_dirs=[...],
        libraries=[...],
        library_dirs=[...]),
    # Everything but primes.pyx is included here.
    Extension("*", ["*.pyx"],
        include_dirs=[...],
        libraries=[...],
        library_dirs=[...]),
]
setup(
    name="My hello app",
    ext_modules=cythonize(extensions),
)

Note that when using setuptools, you should import it before Cython, otherwise,both might disagree about the class to use here.

Note also that if you use setuptools instead of distutils, the defaultaction when running python setup.py install is to create a zippedegg file which will not work with cimport for pxd fileswhen you try to use them from a dependent package.To prevent this, include zip_safe=False in the arguments to setup().

If your options are static (for example you do not need to call a tool likepkg-config to determine them) you can also provide them directly in your.pyx or .pxd source file using a special comment block at the start of the file:

# distutils: libraries = spam eggs
# distutils: include_dirs = /opt/food/include

If you cimport multiple .pxd files defining libraries, then Cythonmerges the list of libraries, so this works as expected (similarlywith other options, like include_dirs above).

If you have some C files that have been wrapped with Cython and you want tocompile them into your extension, you can define the setuptools sourcesparameter:

# distutils: sources = helper.c, another_helper.c

Note that these sources are added to the list of sources of the currentextension module. Spelling this out in the setup.py file looksas follows:

from setuptools import Extension, setup
from Cython.Build import cythonize
 
sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c']
 
extensions = [Extension("example", sourcefiles)]
 
setup(
    ext_modules=cythonize(extensions)
)

The Extension class takes many options, and a fuller explanation canbe found in the setuptools documentation. Some useful options to know aboutare include_dirs, libraries, and library_dirs which specify whereto find the .h and library files when linking to external libraries.

Sometimes this is not enough and you need finer customization of thesetuptools Extension.To do this, you can provide a custom function create_extensionto create the final Extension object after Cython has processedthe sources, dependencies and # distutils directives but before thefile is actually Cythonized.This function takes 2 arguments template and kwds, wheretemplate is the Extension object given as input to Cythonand kwds is a dict with all keywords which should be usedto create the Extension.The function create_extension must return a 2-tuple(extension, metadata), where extension is the createdExtension and metadata is metadata which will be writtenas JSON at the top of the generated C files. This metadata is only usedfor debugging purposes, so you can put whatever you want in there(as long as it can be converted to JSON).The default function (defined in Cython.Build.Dependencies) is:

def default_create_extension(template, kwds):
    if 'depends' in kwds:
        include_dirs = kwds.get('include_dirs', []) + ["."]
        depends = resolve_depends(kwds['depends'], include_dirs)
        kwds['depends'] = sorted(set(depends + template.depends))
 
    t = template.__class__
    ext = t(**kwds)
    metadata = dict(distutils=kwds, module_name=kwds['name'])
    return ext, metadata

In case that you pass a string instead of an Extension tocythonize(), the template will be an Extension withoutsources. For example, if you do cythonize(".pyx"),the template will be Extension(name=".pyx", sources=[]).

Just as an example, this adds mylib as library to every extension:

from Cython.Build.Dependencies import default_create_extension
 
def my_create_extension(template, kwds):
    libs = kwds.get('libraries', []) + ["mylib"]
    kwds['libraries'] = libs
    return default_create_extension(template, kwds)
 
ext_modules = cythonize(..., create_extension=my_create_extension)

Note

If you Cythonize in parallel (using the nthreads argument),then the argument to create_extension must be pickleable.In particular, it cannot be a lambda function.

Cythonize arguments

The function cythonize() can take extra arguments which will allow you tocustomize your build.

• Cython.Build.cythonize(module_list, exclude=None, nthreads=0, aliases=None, quiet=False, force=False, language=None, exclude_failures=False, **options)
• Compile a set of source modules into C/C++ files and return a list of distutilsExtension objects for them.

Parameters:

• module_list – As module list, pass either a glob pattern, a list of globpatterns or a list of Extension objects. The latterallows you to configure the extensions separatelythrough the normal distutils options.You can also pass Extension objects that haveglob patterns as their sources. Then, cythonizewill resolve the pattern and create acopy of the Extension for every matching file.
• exclude – When passing glob patterns as module_list, you can exclude certainmodule names explicitly by passing them into the exclude option.
• nthreads – The number of concurrent builds for parallel compilation(requires the multiprocessing module).
• aliases – If you want to use compiler directives like # distutils: … butcan only know at compile time (when running the setup.py) which valuesto use, you can use aliases and pass a dictionary mapping those aliasesto Python strings when calling cythonize(). As an example, say youwant to use the compilerdirective # distutils: include_dirs = ../static_libs/include/but this path isn’t always fixed and you want to find it when runningthe setup.py. You can then do # distutils: include_dirs = MY_HEADERS,find the value of MY_HEADERS in the setup.py, put it in a pythonvariable called foo as a string, and then callcythonize(…, aliases={'MY_HEADERS': foo}).
• quiet – If True, Cython won’t print error, warning, or status messages during thecompilation.
• force – Forces the recompilation of the Cython modules, even if the timestampsdon’t indicate that a recompilation is necessary.
• language – To globally enable C++ mode, you can pass language='c++'. Otherwise, thiswill be determined at a per-file level based on compiler directives. Thisaffects only modules found based on file names. Extension instances passedinto cythonize() will not be changed. It is recommended to ratheruse the compiler directive # distutils: language = c++ than this option.
• exclude_failures – For a broad ‘try to compile’ mode that ignores compilationfailures and simply excludes the failed extensions,pass exclude_failures=True. Note that this onlyreally makes sense for compiling .py files which can alsobe used without compilation.
• annotate – If True, will produce a HTML file for each of the .pyx or .pyfiles compiled. The HTML file gives an indicationof how much Python interaction there is ineach of the source code lines, compared to plain C code.It also allows you to see the C/C++ codegenerated for each line of Cython code. This report is invaluable whenoptimizing a function for speed,and for determining when to release the GIL:in general, a nogil block may contain only “white” code.See examples in Determining where to add types orPrimes.
• compiler_directives – Allow to set compiler directives in the setup.py like this:compiler_directives={'embedsignature': True}.See Compiler directives.

Multiple Cython Files in a Package

To automatically compile multiple Cython files without listing all of themexplicitly, you can use glob patterns:

setup(
    ext_modules = cythonize("package/*.pyx")
)

You can also use glob patterns in Extension objects if you passthem through cythonize():

extensions = [Extension("*", ["*.pyx"])]
 
setup(
    ext_modules = cythonize(extensions)
)

Distributing Cython modules

It is strongly recommended that you distribute the generated .c files as wellas your Cython sources, so that users can install your module without needingto have Cython available.

It is also recommended that Cython compilation not be enabled by default in theversion you distribute. Even if the user has Cython installed, he/she probablydoesn’t want to use it just to install your module. Also, the installed versionmay not be the same one you used, and may not compile your sources correctly.

This simply means that the setup.py file that you ship with will justbe a normal setuptools file on the generated .c files, for the basic examplewe would have instead:

from setuptools import Extension, setup
 
setup(
    ext_modules = [Extension("example", ["example.c"])]
)

This is easy to combine with cythonize() by changing the file extensionof the extension module sources:

from setuptools import Extension, setup
 
USE_CYTHON = ...   # command line option, try-import, ...
 
ext = '.pyx' if USE_CYTHON else '.c'
 
extensions = [Extension("example", ["example"+ext])]
 
if USE_CYTHON:
    from Cython.Build import cythonize
    extensions = cythonize(extensions)
 
setup(
    ext_modules = extensions
)

If you have many extensions and want to avoid the additional complexity in thedeclarations, you can declare them with their normal Cython sources and thencall the following function instead of cythonize() to adapt the sourceslist in the Extensions when not using Cython:

import os.path
 
def no_cythonize(extensions, **_ignore):
    for extension in extensions:
        sources = []
        for sfile in extension.sources:
            path, ext = os.path.splitext(sfile)
            if ext in ('.pyx', '.py'):
                if extension.language == 'c++':
                    ext = '.cpp'
                else:
                    ext = '.c'
                sfile = path + ext
            sources.append(sfile)
        extension.sources[:] = sources
    return extensions

Another option is to make Cython a setup dependency of your system and useCython’s build_ext module which runs cythonize as part of the build process:

setup(
    extensions = [Extension("*", ["*.pyx"])],
    cmdclass={'build_ext': Cython.Build.new_build_ext},
    ...
)

This depends on pip knowing that Cython is a setup dependency, by havinga pyproject.toml file:

[build-system]
requires = ["setuptools", "wheel", "Cython"]

If you want to expose the C-level interface of your library for otherlibraries to cimport from, use package_data to install the .pxd files,e.g.:

setup(
    package_data = {
        'my_package': ['*.pxd'],
        'my_package/sub_package': ['*.pxd'],
    },
    ...
)

These .pxd files need not have corresponding .pyxmodules if they contain purely declarations of external libraries.

Remember that if you use setuptools instead of distutils, the defaultaction when running python setup.py install is to create a zippedegg file which will not work with cimport for pxd fileswhen you try to use them from a dependent package.To prevent this, include zip_safe=False in the arguments to setup().

Integrating multiple modules

In some scenarios, it can be useful to link multiple Cython modules(or other extension modules) into a single binary, e.g. when embeddingPython in another application. This can be done through the inittabimport mechanism of CPython.

Create a new C file to integrate the extension modules and add thismacro to it:

#if PY_MAJOR_VERSION < 3
# define MODINIT(name)  init ## name
#else
# define MODINIT(name)  PyInit_ ## name
#endif

If you are only targeting Python 3.x, just use PyInit_ as prefix.

Then, for each of the modules, declare its module init functionas follows, replacing some_module_name with the name of the module:

PyMODINIT_FUNC  MODINIT(some_module_name) (void);

In C++, declare them as extern C.

If you are not sure of the name of the module init function, referto your generated module source file and look for a function namestarting with PyInit_.

Next, before you start the Python runtime from your application codewith Py_Initialize(), you need to initialise the modules at runtimeusing the PyImport_AppendInittab() C-API function, again insertingthe name of each of the modules:

PyImport_AppendInittab("some_module_name", MODINIT(some_module_name));

This enables normal imports for the embedded extension modules.

In order to prevent the joined binary from exporting all of the moduleinit functions as public symbols, Cython 0.28 and later can hide thesesymbols if the macro CYTHON_NO_PYINIT_EXPORT is defined whileC-compiling the module C files.

Also take a look at the cython_freeze tool.It can generate the necessary boilerplate code for linking one or moremodules into a single Python executable.

Compiling with pyximport

For building Cython modules during development without explicitlyrunning setup.py after each change, you can use pyximport:

>>> import pyximport; pyximport.install()
>>> import helloworld
Hello World

This allows you to automatically run Cython on every .pyx thatPython is trying to import. You should use this for simple Cythonbuilds only where no extra C libraries and no special building setupis needed.

It is also possible to compile new .py modules that are beingimported (including the standard library and installed packages). Forusing this feature, just tell that to pyximport:

>>> pyximport.install(pyimport=True)

In the case that Cython fails to compile a Python module, pyximportwill fall back to loading the source modules instead.

Note that it is not recommended to let pyximport build codeon end user side as it hooks into their import system. The best wayto cater for end users is to provide pre-built binary packages in thewheel packaging format.

Arguments

The function pyximport.install() can take several arguments toinfluence the compilation of Cython or Python files.

• pyximport.install(pyximport=True, pyimport=False, build_dir=None, build_in_temp=True, setup_args=None, reload_support=False, load_py_module_on_import_failure=False, inplace=False, language_level=None)
• Main entry point for pyxinstall.

Call this to install the .pyx import hook inyour meta-path for a single Python process. If you want it to beinstalled whenever you use Python, add it to your sitecustomize(as described above).

Parameters:

• pyximport – If set to False, does not try to import .pyx files.
• pyimport – You can pass pyimport=True to alsoinstall the .py import hookin your meta-path. Note, however, that it is rather experimental,will not work at all for some .py files and packages, and willheavily slow down your imports due to search and compilation.Use at your own risk.
• build_dir – By default, compiled modules will end up in a .pyxblddirectory in the user’s home directory. Passing a different pathas build_dir will override this.
• build_in_temp – If False, will produce the C files locally. Workingwith complex dependencies and debugging becomes more easy. Thiscan principally interfere with existing files of the same name.
• setup_args – Dict of arguments for Distribution.See distutils.core.setup().
• reload_support – Enables support for dynamicreload(my_module), e.g. after a change in the Cython code.Additional files <so_path>.reloadNN may arise on that account, whenthe previously loaded module file cannot be overwritten.
• load_py_module_on_import_failure – If the compilation of a .pyfile succeeds, but the subsequent import fails for some reason,retry the import with the normal .py module instead of thecompiled module. Note that this may lead to unpredictable resultsfor modules that change the system state during their import, asthe second import will rerun these modifications in whatever statethe system was left after the import of the compiled modulefailed.
• inplace – Install the compiled module(.so for Linux and Mac / .pyd for Windows)next to the source file.
• language_level – The source language level to use: 2 or 3.The default is to use the language level of the current Pythonruntime for .py files and Py2 for .pyx files.

Dependency Handling

Since pyximport does not use cythonize() internally, it currentlyrequires a different setup for dependencies. It is possible to declare thatyour module depends on multiple files, (likely .h and .pxd files).If your Cython module is named foo and thus has the filenamefoo.pyx then you should create another file in the same directorycalled foo.pyxdep. The modname.pyxdep file can be a list offilenames or “globs” (like .pxd or include/.h). Each filename orglob must be on a separate line. Pyximport will check the file date for eachof those files before deciding whether to rebuild the module. In order tokeep track of the fact that the dependency has been handled, Pyximport updatesthe modification time of your “.pyx” source file. Future versions may dosomething more sophisticated like informing setuptools of the dependenciesdirectly.

Limitations

pyximport does not use cythonize(). Thus it is notpossible to do things like using compiler directives atthe top of Cython files or compiling Cython code to C++.

Pyximport does not give you any control over how your Cython file iscompiled. Usually the defaults are fine. You might run into problems ifyou wanted to write your program in half-C, half-Cython and build theminto a single library.

Pyximport does not hide the setuptools/GCC warnings and errors generatedby the import process. Arguably this will give you better feedback ifsomething went wrong and why. And if nothing went wrong it will give youthe warm fuzzy feeling that pyximport really did rebuild your module as itwas supposed to.

Basic module reloading support is available with the option reload_support=True.Note that this will generate a new module filename for each build and thusend up loading multiple shared libraries into memory over time. CPython has limitedsupport for reloading shared libraries as such,see PEP 489.

Pyximport puts both your .c file and the platform-specific binary intoa separate build directory, usually $HOME/.pyxblx/. To copy it backinto the package hierarchy (usually next to the source file) for manualreuse, you can pass the option inplace=True.

Compiling with cython.inline

One can also compile Cython in a fashion similar to SciPy’s weave.inline.For example:

>>> import cython
>>> def f(a):
...     ret = cython.inline("return a+b", b=3)
...

Unbound variables are automatically pulled from the surrounding localand global scopes, and the result of the compilation is cached forefficient re-use.

Compiling with Sage

The Sage notebook allows transparently editing and compiling Cythoncode simply by typing %cython at the top of a cell and evaluateit. Variables and functions defined in a Cython cell are imported into therunning session. Please check Sage documentation for details.

You can tailor the behavior of the Cython compiler by specifying thedirectives below.

Compiling with a Jupyter Notebook

It’s possible to compile code in a notebook cell with Cython.For this you need to load the Cython magic:

%load_ext cython

Then you can define a Cython cell by writing %%cython on top of it.Like this:

%%cython
 
cdef int a = 0
for i in range(10):
    a += i
print(a)

Note that each cell will be compiled into a separate extension module. So if you use a package in a Cythoncell, you will have to import this package in the same cell. It’s not enough tohave imported the package in a previous cell. Cython will tell you that there are“undefined global names” at compilation time if you don’t comply.

The global names (top level functions, classes, variables and modules) of thecell are then loaded into the global namespace of the notebook. So in theend, it behaves as if you executed a Python cell.

Additional allowable arguments to the Cython magic are listed below.You can see them also by typing `%%cython? in IPython or a Jupyter notebook.

Compiler options

Compiler options can be set in the setup.py, before calling cythonize(),like this:

from setuptools import setup
 
from Cython.Build import cythonize
from Cython.Compiler import Options
 
Options.docstrings = False
 
setup(
    name = "hello",
    ext_modules = cythonize("lib.pyx"),
)

Here are the options that are available:

• Cython.Compiler.Options.docstrings = True
• Whether or not to include docstring in the Python extension. If False, the binary sizewill be smaller, but the doc attribute of any class or function will be anempty string.

• Cython.Compiler.Options.embedpos_in_docstring = False_
• Embed the source code position in the docstrings of functions and classes.

• Cython.Compiler.Options.generatecleanup_code = False_
• Decref global variables in each module on exit for garbage collection.0: None, 1+: interned objects, 2+: cdef globals, 3+: types objectsMostly for reducing noise in Valgrind as it typically executes at process exit(when all memory will be reclaimed anyways).Note that directly or indirectly executed cleanup code that makes use of globalvariables or types may no longer be safe when enabling the respective level sincethere is no guaranteed order in which the (reference counted) objects willbe cleaned up. The order can change due to live references and reference cycles.

• Cython.Compiler.Options.clearto_none = True_
• Should tp_clear() set object fields to None instead of clearing them to NULL?

• Cython.Compiler.Options.annotate = False
• Generate an annotated HTML version of the input source files for debugging and optimisation purposes.This has the same effect as the annotate argument in cythonize().

• Cython.Compiler.Options.fastfail = False_
• This will abort the compilation on the first error occurred rather than tryingto keep going and printing further error messages.

• Cython.Compiler.Options.warningerrors = False_
• Turn all warnings into errors.

• Cython.Compiler.Options.erroron_unknown_names = True_
• Make unknown names an error. Python raises a NameError whenencountering unknown names at runtime, whereas this option makesthem a compile time error. If you want full Python compatibility,you should disable this option and also ‘cache_builtins’.

• Cython.Compiler.Options.erroron_uninitialized = True_
• Make uninitialized local variable reference a compile time error.Python raises UnboundLocalError at runtime, whereas this option makesthem a compile time error. Note that this option affects only variablesof “python object” type.

• Cython.Compiler.Options.convertrange = True_
• This will convert statements of the form for i in range(…)to for i from … when i is a C integer type, and the direction(i.e. sign of step) can be determined.WARNING: This may change the semantics if the range causes assignment toi to overflow. Specifically, if this option is set, an error will beraised before the loop is entered, whereas without this option the loopwill execute until an overflowing value is encountered.

• Cython.Compiler.Options.cachebuiltins = True_
• Perform lookups on builtin names only once, at module initialisationtime. This will prevent the module from getting imported if abuiltin name that it uses cannot be found during initialisation.Default is True.Note that some legacy builtins are automatically remappedfrom their Python 2 names to their Python 3 names by Cythonwhen building in Python 3.x,so that they do not get in the way even if this option is enabled.

• Cython.Compiler.Options.gccbranch_hints = True_
• Generate branch prediction hints to speed up error handling etc.

• Cython.Compiler.Options.lookupmodule_cpdef = False_
• Enable this to allow one to write your_module.foo = … to overwrite thedefinition if the cpdef function foo, at the cost of an extra dictionarylookup on every call.If this is false it generates only the Python wrapper and no override check.

• Cython.Compiler.Options.embed = None
• Whether or not to embed the Python interpreter, for use in making astandalone executable or calling from external libraries.This will provide a C function which initialises the interpreter andexecutes the body of this module.See this demofor a concrete example.If true, the initialisation function is the C main() function, butthis option can also be set to a non-empty string to provide a function name explicitly.Default is False.

• Cython.Compiler.Options.cimportfrom_pyx = False_
• Allows cimporting from a pyx file without a pxd file.

• Cython.Compiler.Options.buffermax_dims = 8_
• Maximum number of dimensions for buffers – set lower than number ofdimensions in numpy, asslices are passed by value and involve a lot of copying.

• Cython.Compiler.Options.closurefreelist_size = 8_
• Number of function closure instances to keep in a freelist (0: no freelists)

Compiler directives

Compiler directives are instructions which affect the behavior ofCython code. Here is the list of currently supported directives:

• binding (True / False)
• Controls whether free functions behave more like Python’s CFunctions(e.g. len()) or, when set to True, more like Python’s functions.When enabled, functions will bind to an instance when looked up as aclass attribute (hence the name) and will emulate the attributesof Python functions, including introspections like argument names andannotations.

Default is True.

Changed in version 3.0.0: Default changed from False to True

• boundscheck (True / False)
• If set to False, Cython is free to assume that indexing operations([]-operator) in the code will not cause any IndexErrors to beraised. Lists, tuples, and strings are affected only if the indexcan be determined to be non-negative (or if wraparound is False).Conditions which would normally trigger an IndexError may instead causesegfaults or data corruption if this is set to False.Default is True.
• wraparound (True / False)
• In Python, arrays and sequences can be indexed relative to the end.For example, A[-1] indexes the last value of a list.In C, negative indexing is not supported.If set to False, Cython is allowed to neither check for nor correctlyhandle negative indices, possibly causing segfaults or data corruption.If bounds checks are enabled (the default, see boundschecks above),negative indexing will usually raise an IndexError for indices thatCython evaluates itself.However, these cases can be difficult to recognise in user code todistinguish them from indexing or slicing that is evaluated by theunderlying Python array or sequence object and thus continues to supportwrap-around indices.It is therefore safest to apply this option only to code that does notprocess negative indices at all.Default is True.
• initializedcheck (True / False)
• If set to True, Cython checks that a memoryview is initializedwhenever its elements are accessed or assigned to. Setting thisto False disables these checks.Default is True.
• nonecheck (True / False)
• If set to False, Cython is free to assume that native fieldaccesses on variables typed as an extension type, or bufferaccesses on a buffer variable, never occurs when the variable isset to None. Otherwise a check is inserted and theappropriate exception is raised. This is off by default forperformance reasons. Default is False.
• overflowcheck (True / False)
• If set to True, raise errors on overflowing C integer arithmeticoperations. Incurs a modest runtime penalty, but is much faster thanusing Python ints. Default is False.
• overflowcheck.fold (True / False)
• If set to True, and overflowcheck is True, check the overflow bit fornested, side-effect-free arithmetic expressions once rather than at everystep. Depending on the compiler, architecture, and optimization settings,this may help or hurt performance. A simple suite of benchmarks can befound in Demos/overflow_perf.pyx. Default is True.
• embedsignature (True / False)
• If set to True, Cython will embed a textual copy of the callsignature in the docstring of all Python visible functions andclasses. Tools like IPython and epydoc can thus display thesignature, which cannot otherwise be retrieved aftercompilation. Default is False.
• cdivision (True / False)
• If set to False, Cython will adjust the remainder and quotientoperators C types to match those of Python ints (which differ whenthe operands have opposite signs) and raise aZeroDivisionError when the right operand is 0. This has up toa 35% speed penalty. If set to True, no checks are performed. SeeCEP 516. Defaultis False.
• cdivision_warnings (True / False)
• If set to True, Cython will emit a runtime warning wheneverdivision is performed with negative operands. See CEP 516. Default isFalse.
• always_allow_keywords (True / False)
• Avoid the METH_NOARGS and METH_O when constructingfunctions/methods which take zero or one arguments. Has no effecton special methods and functions with more than one argument. TheMETH_NOARGS and METH_O signatures provide fastercalling conventions but disallow the use of keywords.
• profile (True / False)
• Write hooks for Python profilers into the compiled C code. Defaultis False.
• linetrace (True / False)
• Write line tracing hooks for Python profilers or coverage reportinginto the compiled C code. This also enables profiling. Default isFalse. Note that the generated module will not actually use linetracing, unless you additionally pass the C macro definitionCYTHON_TRACE=1 to the C compiler (e.g. using the setuptools optiondefine_macros). Define CYTHON_TRACE_NOGIL=1 to also includenogil functions and sections.
• infer_types (True / False)
• Infer types of untyped variables in function bodies. Default isNone, indicating that only safe (semantically-unchanging) inferencesare allowed.In particular, inferring integral types for variables used in arithmeticexpressions is considered unsafe (due to possible overflow) and must beexplicitly requested.
• language_level (2/3/3str)
• Globally set the Python language level to be used for modulecompilation. Default is compatibility with Python 2. To enablePython 3 source code semantics, set this to 3 (or 3str) at the startof a module or pass the “-3” or “–3str” command line options to thecompiler. The 3str option enables Python 3 semantics but doesnot change the str type and unprefixed string literals tounicode when the compiled code runs in Python 2.x.Note that cimported files inherit this setting from the modulebeing compiled, unless they explicitly set their own language level.Included source files always inherit this setting.
• c_string_type (bytes / str / unicode)
• Globally set the type of an implicit coercion from char* or std::string.
• c_string_encoding (ascii, default, utf-8, etc.)
• Globally set the encoding to use when implicitly coercing char* or std:stringto a unicode object. Coercion from a unicode object to C type is only allowedwhen set to ascii or default, the latter being utf-8 in Python 3 andnearly-always ascii in Python 2.
• type_version_tag (True / False)
• Enables the attribute cache for extension types in CPython by setting thetype flag Py_TPFLAGS_HAVE_VERSION_TAG. Default is True, meaning thatthe cache is enabled for Cython implemented types. To disable itexplicitly in the rare cases where a type needs to juggle with its tp_dictinternally without paying attention to cache consistency, this option canbe set to False.
• unraisable_tracebacks (True / False)
• Whether to print tracebacks when suppressing unraisable exceptions.
• iterable_coroutine (True / False)
• PEP 492 specifies that async-defcoroutines must not be iterable, in order to prevent accidental misuse innon-async contexts. However, this makes it difficult and inefficient to writebackwards compatible code that uses async-def coroutines in Cython but needs tointeract with async Python code that uses the older yield-from syntax, such asasyncio before Python 3.5. This directive can be applied in modules orselectively as decorator on an async-def coroutine to make the affectedcoroutine(s) iterable and thus directly interoperable with yield-from.
• annotation_typing (True / False)
• Uses function argument annotations to determine the type of variables. Defaultis True, but can be disabled. Since Python does not enforce types given inannotations, setting to False gives greater compatibility with Python code.Must be set globally.
• emit_code_comments (True / False)
• Copy the original source code line by line into C code comments in the generatedcode file to help with understanding the output.This is also required for coverage analysis.

Configurable optimisations

• optimize.use_switch (True / False)
• Whether to expand chained if-else statements (including statements likeif x == 1 or x == 2:) into C switch statements. This can have performancebenefits if there are lots of values but cause compiler errors if there are anyduplicate values (which may not be detectable at Cython compile time for allC constants). Default is True.
• optimize.unpack_method_calls (True / False)
• Cython can generate code that optimistically checks for Python method objectsat call time and unpacks the underlying function to call it directly. Thiscan substantially speed up method calls, especially for builtins, but may alsohave a slight negative performance impact in some cases where the guess goescompletely wrong.Disabling this option can also reduce the code size. Default is True.

Warnings

All warning directives take True / False as optionsto turn the warning on / off.

• warn.undeclared (default False)
• Warns about any variables that are implicitly declared without a cdef declaration
• warn.unreachable (default True)
• Warns about code paths that are statically determined to be unreachable, e.g.returning twice unconditionally.
• warn.maybe_uninitialized (default False)
• Warns about use of variables that are conditionally uninitialized.
• warn.unused (default False)
• Warns about unused variables and declarations
• warn.unused_arg (default False)
• Warns about unused function arguments
• warn.unused_result (default False)
• Warns about unused assignment to the same name, such asr = 2; r = 1 + 2
• warn.multiple_declarators (default True)
• Warns about multiple variables declared on the same line with at least one pointer type.For example cdef double* a, b - which, as in C, declares a as a pointer, b asa value type, but could be mininterpreted as declaring two pointers.

How to set directives

Globally

One can set compiler directives through a special header comment near the top of the file, like this:

# cython: language_level=3, boundscheck=False

The comment must appear before any code (but can appear after othercomments or whitespace).

One can also pass a directive on the command line by using the -X switch:

$ cython -X boundscheck=True ...

Directives passed on the command line will override directives set inheader comments.

Locally

For local blocks, you need to cimport the special builtin cythonmodule:

#!python
cimport cython

Then you can use the directives either as decorators or in a withstatement, like this:

#!python
@cython.boundscheck(False) # turn off boundscheck for this function
def f():
    ...
    # turn it temporarily on again for this block
    with cython.boundscheck(True):
        ...

Warning

These two methods of setting directives are notaffected by overriding the directive on the command-line using the-X option.

In setup.py

Compiler directives can also be set in the setup.py file by passing a keywordargument to cythonize:

from setuptools import setup
from Cython.Build import cythonize
 
setup(
    name="My hello app",
    ext_modules=cythonize('hello.pyx', compiler_directives={'embedsignature': True}),
)

This will override the default directives as specified in the compiler_directives dictionary.Note that explicit per-file or local directives as explained above take precedence over thevalues passed to cythonize.