The Cython language makes writing C extensions for the Python language as easy as Python itself. Cython is a source code translator based on Pyrex_, but supports more cutting edge functionality and optimizations.
The Cython language is a superset of the Python language (almost all Python code is also valid Cython code), but Cython additionally supports optional static typing to natively call C functions, operate with C++ classes and declare fast C types on variables and class attributes. This allows the compiler to generate very efficient C code from Cython code.
This makes Cython the ideal language for writing glue code for external C/C++ libraries, and for fast C modules that speed up the execution of Python code.
The newest Cython release can always be downloaded from https://cython.org/. Unpack the tarball or zip file, enter the directory, and then run::
pip install .
Note that for one-time builds, e.g. for CI/testing, on platforms that are not covered by one of the wheel packages provided on PyPI and the pure Python wheel that we provide is not used, it is substantially faster than a full source build to install an uncompiled (slower) version of Cython with::
NO_CYTHON_COMPILE=true pip install .
.. _Pyrex: https://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/
3.1.0 rc 2 (2025-05-07):
Declarations for C++ std::stop_token were added as libcpp.stop_token to provide
additional low-level synchronisation primitives also in the light of free-threading Python.
(Github issue https://github.com/cython/cython/issues/6820)
The generation of the shared module now happens automatically from cythonize() in a
setuptools build if a corresponding Extension has been configured.
This avoids an additional step outside of the setup.py or pip wheel run.
(Github issue https://github.com/cython/cython/issues/6842)
3.1.0 rc 1 (2025-05-01):
cython.pymutex provides a fast mutex by wrapping the new PyMutex feature of recent
CPython versions (including free-threading) and falls back to PyThread locks in older Pythons.
(Github issue https://github.com/cython/cython/issues/6579)
A new directive subinterpreters_compatible=shared_gil/own_gil was added to allow modules
to declare support for subinterpreters.
(Github issue https://github.com/cython/cython/issues/6513)
divmod() is also optimised for C floating point types and can be called on C number types
without holding the GIL.
(Github issue https://github.com/cython/cython/issues/6801)
New C++ declarations were added. (Github issues https://github.com/cython/cython/issues/6625, https://github.com/cython/cython/issues/6731)
embedsignature now works for special methods (if they have a docstring).
(Github issue https://github.com/cython/cython/issues/1577)
3.1.0 beta 1 (2025-04-03):
Global cdef const … variables are supported.
(Github issue https://github.com/cython/cython/issues/6542)
A new context manager / function decorator cython.critical_section was added
wrapping Python's critical section C-API feature.
(Github issues https://github.com/cython/cython/issues/6516, https://github.com/cython/cython/issues/6577)
Some common Cython-internal code (currently only memoryview related) can now be extracted into a shared extension module to reduce the installed overall size of a package with many Cython compiled modules. (Github issue https://github.com/cython/cython/issues/2356)
The type of prange loop targets is now inferred.
(Github issue https://github.com/cython/cython/issues/6585)
Extracting keyword arguments is faster in some cases. (Github issue https://github.com/cython/cython/issues/6683)
Calling divmod() on any C integer types is efficient.
(Github issue https://github.com/cython/cython/issues/6717)
Some async/coroutine/vectorcall code has improved fast-paths. (Github issues https://github.com/cython/cython/issues/6732, https://github.com/cython/cython/issues/6735, https://github.com/cython/cython/issues/6736, https://github.com/cython/cython/issues/6738, https://github.com/cython/cython/issues/6742, https://github.com/cython/cython/issues/6771)
Calls to Python builtins and extension types use the vectorcall protocol. (Github issue https://github.com/cython/cython/issues/6744)
Method calls use PyObject_VectorcallMethod() where possible.
(Github issue https://github.com/cython/cython/issues/6747)
Some C-API shortcuts were (re-)added. (Github issue https://github.com/cython/cython/issues/6761)
Cython can avoid normalising exceptions in an except clause if it knows that they are unused.
(Github issue https://github.com/cython/cython/issues/6601)
The cython command has a new option --cache to cache generated files.
(Github issue https://github.com/cython/cython/issues/6091)
The cythonize command has a new option --timeit to benchmark Cython code snippets.
(Github issue https://github.com/cython/cython/issues/6697)
The argument parsing cygdb command was improved based on argparse.
Patch by William Ayd. (Github issue https://github.com/cython/cython/issues/5499)
The PyWeakref_GetRef declaration was added to cpython.weakref and backported.
Patch by Lysandros Nikolaou. (Github issue https://github.com/cython/cython/issues/6478)
std::span declarations were added to libcpp.
Patch by Alexander Condello. (Github issue https://github.com/cython/cython/issues/6539)
std::string_view declarations were added to libcpp.
Patch by Antoine Pitrou. (Github issue https://github.com/cython/cython/issues/6539)
Mutex declarations for libc and libcpp were added.
(Github issue https://github.com/cython/cython/issues/6610)
Several C++ declarations were improved and extended. Patches by Yury V. Zaytsev. (Github issues https://github.com/cython/cython/issues/488, https://github.com/cython/cython/issues/489)
Bazel build rules were updated for better interoperability. Patch by maleo. (Github issue https://github.com/cython/cython/issues/6478)
The Demos/benchmarks/ directory include a new benchmark runner that can run selected
benchmarks against different Cython git revisions.
3.1.0 alpha 1 (2024-11-08):
Support for freethreading builds of CPython 3.13 was added.
It comes with a new directive freethreading_compatible=True to mark modules as
free-threading compatible (Py_mod_gil).
https://github.com/cython/cython/issues?q=label%3A%22nogil+CPython%22
Patches by Lysandros Nikolaou and Nathan Goldbaum. (Github issue https://github.com/cython/cython/issues/6162)
Support for monitoring Cython modules via sys.monitoring in CPython 3.13+ was added.
For coverage reporting, this needs to be disabled with -DCYTHON_USE_SYS_MONITORING=0
as long as coverage.py does not support sys.monitoring for coverage plugins.
(Github issue https://github.com/cython/cython/issues/6144)
Many issues with the Limited C-API were resolved.
It is now sufficient to define the macro Py_LIMITED_API to activate the support.
https://github.com/cython/cython/issues?q=label%3A%22limited+api%22
Support for GraalPython was improved (but is still incomplete).
Several issues with the gdb support were resolved. Patches by Kent Slaney. (Github issues https://github.com/cython/cython/issues/5955, https://github.com/cython/cython/issues/5948)
typing.Union[SomeType, None] and SomeType | None are now understood and mean
the same as typing.Optional[SomeType], allowing None in type checks.
(Github issue https://github.com/cython/cython/issues/6254)
cython.const[] and cython.volatile[] are now available as type modifiers in Python code.
(Github issue https://github.com/cython/cython/issues/5728)
cython.pointer[SomeCType] can now be used to define pointer types in Python type annotations.
(Github issue https://github.com/cython/cython/issues/5071)
Several improvements were made to reduce the size of the resulting extension modules. (Github issue https://github.com/cython/cython/issues/4425)
Function calls now use the PEP-590 Vectorcall protocol, even when passing keyword arguments. (Github issues https://github.com/cython/cython/issues/5804)
Coroutines now use the am_send slot function instead of going through a Python .send() call.
This has been backported for Python 3.7 - 3.9.
(Github issues https://github.com/cython/cython/issues/4585)
__set_name__ is called when assigning to class attributes.
(Github issue https://github.com/cython/cython/issues/6179)
Most builtin methods now provide their return type for type inference. (Github issues https://github.com/cython/cython/issues/4829, https://github.com/cython/cython/issues/5865, https://github.com/cython/cython/issues/6412)
Method calls on builtin literal values are evaluated at compile time, if applicable. (Github issue https://github.com/cython/cython/issues/6383)
The Python int type now maps directly to PyLong and is inferred accordingly.
(Github issue https://github.com/cython/cython/issues/4237)
Integer operations on known int types are faster.
(Github issue https://github.com/cython/cython/issues/5785)
f-strings are faster in some cases. (Github issues https://github.com/cython/cython/issues/5866, https://github.com/cython/cython/issues/6342, https://github.com/cython/cython/issues/6383)
divmod() is faster on C int.
Patch by Tong He. (Github issue https://github.com/cython/cython/issues/6073)
dict.pop() is faster in some cases.
(Github issue https://github.com/cython/cython/issues/5911)
.isprintable() is optimised for Unicode characters.
(Github issue https://github.com/cython/cython/issues/3277)
x in () and similar tests against empty constant sequences (e.g. in generated code)
are now discarded if they have no side-effects.
(Github issue https://github.com/cython/cython/issues/6288)
Constant (non-GC) Python objects are no longer traversed with Py_VISIT() during GC runs.
(Github issue https://github.com/cython/cython/issues/6277)
C++ classes implemented in Cython can now use method overloading. Patch by samaingw. (Github issue https://github.com/cython/cython/issues/3235)
Assigning a Python container to a C++ vector now makes use of __length_hint__
to avoid reallocations.
Patch by Denis Lukianov. (Github issue https://github.com/cython/cython/issues/6077)
The C++11 emplace* methods were added to libcpp.deque.
Patch by Somin An. (Github issue https://github.com/cython/cython/issues/6159)
cpython.time was updated and extended for Python 3.13.
(Github issue https://github.com/cython/cython/issues/6187)
Dataclasses support the match_args option.
(Github issue https://github.com/cython/cython/issues/5381)
Threading in parallel sections can now be disabled with a new use_threads_if condition.
(Github issue https://github.com/cython/cython/issues/5919)
New options warn.deprecated.DEF and warn.deprecated.IF can silence the deprecation warnings.
Patch by Eric Larson. (Github issue https://github.com/cython/cython/issues/6243)
cygdb shows more helpful output for some objects.
Patch by Kent Slaney. (Github issue https://github.com/cython/cython/issues/5958)
Bazel build support for improved. Patch by mering. (Github issue https://github.com/cython/cython/issues/6452)
The parser was updated for Unicode 15.1 (as provided by CPython 3.13b4).
3.1.0 rc 2 (2025-05-07):
Variables typed as builtin Python exception types now accept subtypes instead of rejecting them.
This specifically impacted types like BaseException, Exception or OSError,
which almost always intend to reference subtypes.
(Github issue https://github.com/cython/cython/issues/6828)
Functions with more than 10 constant default argument values could generate invalid C code. (Github issue https://github.com/cython/cython/issues/6843)
The call_once() function argument in libc.threads (new in 3.1) was changed to require
a nogil declaration, as semantically implied. Code that used it with a callback function
expecting to hold the GIL must change the callback code to use with gil.
Calling cimported C functions with their fully qualified package name could crash Cython. (Github issue https://github.com/cython/cython/issues/6551)
Naming a variable after its inferred type (e.g. str += "") could trigger an infinite loop in Cython.
(Github issue https://github.com/cython/cython/issues/6835)
Cython is more relaxed about the exact C++ constructor name when it calls new() on ctypedefs.
(Github issue https://github.com/cython/cython/issues/6821)
Using cpp_locals in nogil sections could crash.
(Github issue https://github.com/cython/cython/issues/6838)
const struct declarations could lead to invalid assignments to const temp variables.
(Github issue https://github.com/cython/cython/issues/6804)
A refcounting error was fixed in the method class cell support code. (Github issue https://github.com/cython/cython/issues/6839)
3.1.0 rc 1 (2025-05-01):
Iterating over literal sequences in generator expressions could generate invalid C code. (Github issue https://github.com/cython/cython/issues/6725)
Tracing could generate invalid C code. (Github issue https://github.com/cython/cython/issues/6781)
Non-ASCII function argument names could generate invalid C code. (Github issue https://github.com/cython/cython/issues/6813)
Optimised divmod() calls could produce incorrect results in beta-1 due to incorrect C type usage.
(Github issue https://github.com/cython/cython/issues/6786)
Raising UnboundLocalError could fail for non-ascii variable names.
(Github issue https://github.com/cython/cython/issues/6800)
The signature of PyByteArray_Resize() in cpython.bytearray failed to propagate exceptions.
Patch by Kirill Smelkov. (Github issue https://github.com/cython/cython/issues/6787)
Some more issues with the Limited C-API and free-threading Python were resolved.
https://github.com/cython/cython/issues?q=label%3A%22limited+api%22
https://github.com/cython/cython/issues?q=label%3A%22nogil+CPython%22
The signature of cythonize_one() accidentally changed in 3.1.0b1.
(Github issue https://github.com/cython/cython/issues/6815)
3.1.0 beta 1 (2025-04-03):
Many issues with the Limited C-API and free-threading Python were resolved. This includes better thread-safety of Cython-internal types like functions and generators.
https://github.com/cython/cython/issues?q=label%3A%22limited+api%22
https://github.com/cython/cython/issues?q=label%3A%22nogil+CPython%22
for-in loops could generate invalid code for C++ containers.
Patch by Taras Kozlov. (Github issue https://github.com/cython/cython/issues/6578)
PyDict_GetItemRef() and PyList_GetItemRef() were not always used correctly.
Patch by Lisandro Dalcin. (Github issue https://github.com/cython/cython/issues/6647)
Inlined calls to local functions could crash with binding=False.
(Github issue https://github.com/cython/cython/issues/6556)
Calling sorted() could crash in 3.1.0a1.
(Github issue https://github.com/cython/cython/issues/6496)
Calling 0-arg methods was unnecessarily slow in 3.1.0a1. (Github issue https://github.com/cython/cython/issues/6730)
A crash when reading the interpreter ID was fixed.
Crashes while tracing C function returns were resolved. (Github issue https://github.com/cython/cython/issues/6503)
A compiler crash on complex/complex was resolved.
(Github issue https://github.com/cython/cython/issues/6552)
A compiler crash when using the cpp_locals directive was resolved.
(Github issue https://github.com/cython/cython/issues/6370)
Name mangling did not work correctly for attributes of extension types that have reserved C names. (Github issue https://github.com/cython/cython/issues/6678)
Declaring a @staticmethod in a pxd file and overriding it in a subclass could
trigger incorrect "declared but not defined" errors.
Patch by Aditya Pillai. (Github issue https://github.com/cython/cython/issues/6714)
Cython's fake code objects are now compatible with GraalPython. (Github issue https://github.com/cython/cython/issues/6409)
Stepping through foreign code with cygdb could fail with an IndexError.
Patch by clayote. (Github issue https://github.com/cython/cython/issues/6552)
Some PyPy incompatibilities were resolved. Patches by Matti Picus. (Github issue https://github.com/cython/cython/issues/6592, https://github.com/cython/cython/issues/6640)
Interoperability with recent Pythran releases was fixed. (Github issue https://github.com/cython/cython/issues/6494)
The gdb compatibility of cygdb was improved.
Patch by Kent Slaney. (Github issue https://github.com/cython/cython/issues/6681)
Some redundant exception normalisation work was removed in Python 3.12+. (Github issue https://github.com/cython/cython/issues/6599)
A compiler hang introduced in 3.1a1 when overriding methods was resolved. Patch by Aditya Pillai. (Github issue https://github.com/cython/cython/issues/6704)
A compiler crash was resolved when trying to issue a warning. Patch by Gabriele N. Tornetta. (Github issue https://github.com/cython/cython/issues/6711)
Some incomplete import time "safety checks" from 3.1.0a1 were removed again. (Github issue https://github.com/cython/cython/issues/6671)
Using the common_utility_include_dir option in parallel builds on Windows could fail.
Some "unused" warnings from the C compiler were resolved. Patches by Lisandro Dalcin. (Github issue https://github.com/cython/cython/issues/6726)
3.1.0 alpha 1 (2024-11-08):
C functions used different start lines and columns for error reporting and tracing than Python functions. They now use the line and column of their first decorator or (if none) their definition line, as in Python. (Github issue https://github.com/cython/cython/issues/6366)
Dataclasses did not handle default fields without init value correctly. (Github issue https://github.com/cython/cython/issues/5858)
Implementing a special method based on another could lead to infinite recursion. (Github issue https://github.com/cython/cython/issues/5863)
The __class__ cell variable in methods was not always working as in Python.
Initial patch by Tom Keefe. (Github issue https://github.com/cython/cython/issues/2912)
Lambda functions had no code objects. Their signature can now be introspected. (Github issue https://github.com/cython/cython/issues/2983)
Subtyping complex as extension type could fail.
(Github issue https://github.com/cython/cython/issues/6346)
hasattr() now propagates exceptions that occur during lookup.
(Github issue https://github.com/cython/cython/issues/6269)
The base type of extension heap types is now traversed during GC runs in Py3.9+. (Github issue https://github.com/cython/cython/issues/4193)
The Python & operator could touch invalid memory with certain 0 values in Python <= 3.10.
Patch by Michael J. Sullivan. (Github issue https://github.com/cython/cython/issues/4193)
Exception values were not always recognised as equal at compile time. (Github issue https://github.com/cython/cython/issues/5709)
Running Cython in different Python versions could generate slightly different C code due to differences in the builtins. (Github issue https://github.com/cython/cython/issues/5591)
The common_include_dir feature used different file paths in the C code on Windows and Posix.
It now uses forward slashes as directory separator consistently.
(Github issue https://github.com/cython/cython/issues/6355)
File paths in the C code are now relative to the build directory. Patch by Oscar Benjamin. (Github issue https://github.com/cython/cython/issues/6341)
depfiles now use relative paths whenever possible. Patch by Loïc Estève. (Github issue https://github.com/cython/cython/issues/6345)
The -a option in the IPython magic no longer copies the complete HTML document
into the notebook but only a more reasonable content snippet.
Patch by Min RK. (Github issue https://github.com/cython/cython/issues/5760)
Uselessly referring to C enums (not enum values) as Python objects is now rejected. Patch by Vyas Ramasubramani. (Github issue https://github.com/cython/cython/issues/5638)
Cython no longer acquires the GIL during in-place assignments to C attributes in nogil sections. Patch by Mads Ynddal. (Github issue https://github.com/cython/cython/issues/6407)
Several C++ warnings about char* casts were resolved.
(Github issues https://github.com/cython/cython/issues/5515, https://github.com/cython/cython/issues/5847)
C++ undefined behaviour was fixed in an error handling case. (Github issue https://github.com/cython/cython/issues/5278)
Dict assignments to struct members with reserved C/C++ names could generate invalid C code.
The PEP-479 implementation could raise a visible RuntimeError without
a trace of the original StopIteration.
(Github issue https://github.com/cython/cython/issues/5953)
A crash was fixed when assigning a zero-length slice to a memoryview. Patch by Michael Man. (Github issue https://github.com/cython/cython/issues/6227)
Conditionally assigning to variables with the walrus operator could crash. (Github issue https://github.com/cython/cython/issues/6094)
Unterminated string literals could lock up the build in an infinite loop. (Github issue https://github.com/cython/cython/issues/5977)
Exporting C functions uses better platform compatible code. (Github issue https://github.com/cython/cython/issues/4683)
The shebang in libpython.py was incorrect.
Patch by Luke Hamburg. (Github issue https://github.com/cython/cython/issues/6439)
Cython now uses SHA-256 instead of SHA-1 for caching etc. as the latter may not be
available on all Python installations.
(Github issue https://github.com/cython/cython/issues/6354)
3.0.12 (2025-02-11):
Release 3.0.11 introduced some incorrect noexcept warnings.
(Github issue https://github.com/cython/cython/issues/6335)
Conditional assignments to variables using the walrus operator could crash. (Github issue https://github.com/cython/cython/issues/6094)
Dict assignments to struct members with reserved C names could generate invalid C code.
Fused ctuples with the same entry types but different sizes could fail to compile. (Github issue https://github.com/cython/cython/issues/6328)
In Py3, pyximport was not searching sys.path when looking for importable source files.
(Github issue https://github.com/cython/cython/issues/5615)
Using & 0 on integers produced with int.from_bytes() could read invalid memory on Python 3.10.
(Github issue https://github.com/cython/cython/issues/6480)
Modules could fail to compile in PyPy 3.11 due to missing CPython specific header files. Patch by Matti Picus. (Github issue https://github.com/cython/cython/issues/6482)
Minor fix in C++ partial_sum() declaration.
3.0.11 (2024-08-05):
The exception check value of functions declared in pxd files was not always applied in 3.0.10. (Github issue https://github.com/cython/cython/issues/6122)
A crash on exception deallocations was fixed. (Github issue https://github.com/cython/cython/issues/6022)
A crash was fixed when assigning a zero-length slice to a memoryview. Patch by Michael Man. (Github issue https://github.com/cython/cython/issues/6227)
libcpp.optional.value() could crash if it raised a C++ exception.
Patch by Alexander Condello. (Github issue https://github.com/cython/cython/issues/6190)
The return type of str() was mishandled, leading to crashes with language_level=3.
(Github issue https://github.com/cython/cython/issues/6166)
bytes.startswith/endswith() failed for non-bytes substrings (e.g. bytearray).
(Github issue https://github.com/cython/cython/issues/6168)
Fused ctuples crashed Cython. (Github issue https://github.com/cython/cython/issues/6068)
A compiler crash was fixed when using extension types in fused types. (Github issue https://github.com/cython/cython/issues/6204)
The module cleanup code was incorrect for globally defined memory view slices. (Github issue https://github.com/cython/cython/issues/6276)
Some adaptations were made to enable compilation in Python 3.13. (Github issues https://github.com/cython/cython/issues/5997, https://github.com/cython/cython/issues/6182, https://github.com/cython/cython/issues/6251)
3.1.0 rc 1 (2025-05-01):
cpdef enums no longer copy their item names into the global module namespace.
This was considered unhelpful for named enums which already live in their own class namespace.
In cases where the old behaviour was desired, users can add the following backwards compatible
command after their enum class definition: globals().update(getattr(TheUserEnumClass, '__members__')).
Anonymous enums still produce global item names, as before.
(Github issue https://github.com/cython/cython/issues/4571)3.1.0 beta 1 (2025-04-03):
All Cython-internal types (functions, coroutines, …) are now heap types and use type specs. (Github issue https://github.com/cython/cython/issues/6633)
Tracing/monitoring is now disabled in parallel/prange sections. (Github issue https://github.com/cython/cython/issues/6709)
The numpy.math cimport module has been deprecated.
Usages should be replaced by libc.math.
(Github issue https://github.com/cython/cython/issues/6743)
Includes all fixes as of Cython 3.0.12.
3.1.0 alpha 1 (2024-11-08):
Support for Python 2.7 - 3.7 was removed, along with large chunks of legacy code. (Github issue https://github.com/cython/cython/issues/2800)
The pxd files cpython.int, cpython.cobject, cpython.oldbuffer and cpython.string
were removed as they refer to C-API declarations that are only in Python 2.x.
(Github issue https://github.com/cython/cython/issues/5870)
The generated C code now requires a C99 compatible C compiler.
language_level=3 is now the default.
language_level=3str has become a legacy alias.
(Github issue https://github.com/cython/cython/issues/5827)
The Py2 types unicode and basestring are now deprecated and have become aliases
of the str type.
(Github issue https://github.com/cython/cython/issues/6374)
Docstrings now strip their leading whitespace according to PEP-257. Patch by Lawrence Mitchell. (Github issue https://github.com/cython/cython/issues/6241)
Type checkers should have it easier to find and validate Cython types in .py files. (Github issue https://github.com/cython/cython/issues/4327)
The previously shipped NumPy C-API declarations (cimport numpy) were removed.
NumPy has been providing version specific declarations for several versions now.
(Github issue https://github.com/cython/cython/issues/5842)
Usages of the outdated WITH_THREAD macro guard were removed.
(Github issue https://github.com/cython/cython/issues/5812)
The options for showing the C code line in Python exception stack traces were cleaned up.
Previously, disabling the option with the CYTHON_CLINE_IN_TRACEBACK macro did not
reduce the code overhead of the feature, and the c_line_in_traceback compile option
was partly redundant with the C macro switches and lead to warnings about unused code.
Since this is considered mostly a debug feature, the new default is that it is disabled
to avoid code and runtime overhead. It can be enabled by setting the C macro to 1, and
a new macro CYTHON_CLINE_IN_TRACEBACK_RUNTIME was added that controls the runtime
configurable setting if the feature is enabled, which was previously only available
through the compile option. The compile option is now deprecated (but still available),
and users should migrate to using the two C macros only.
(Github issue https://github.com/cython/cython/issues/6036)
Includes all fixes as of Cython 3.0.11 (but generates C99 code in some places).