Cython "Cython.Compiler.Errors" - Compile Failure in CI

By Kaveh Alemi·Latchkey

A Cython-backed package compiles .pyx to C and then to a binary. Builds fail when Cython is absent from the build env, when a vendored .c is regenerated against an incompatible Cython, or on a genuine Cython syntax error.

What this error means

A source build fails with a Cython.Compiler.Errors.CompileError, Cython is required to compile, or a C error from generated code. There is no wheel, so pip ran the Cython compile step.

Build output

Error compiling Cython file:
------------------------------------------------------------
  cdef int total = sum(values
                              ^
------------------------------------------------------------
src/fast.pyx:42:30: Expected ')', found newline

Diagnose it: is it the build backend or a missing system library?

Python packaging failures in CI split into build-backend configuration problems and missing system headers. The traceback usually points at the backend even when the real cause is an absent -dev package.

Terminal

python -m pip install --upgrade pip build
python -m build --wheel 2>&1 | tail -40

# a compiler error naming a .h file is a system dependency, not a Python one
#   e.g. "Python.h: No such file" -> python3-dev
#        "openssl/ssl.h"          -> libssl-dev

Common causes

Cython missing from the build environment

If the project needs Cython to compile .pyx but does not list it in [build-system] requires, the isolated build env has no Cython and fails.

A genuine Cython source error

A syntax or language-level error in a .pyx file (or one surfaced by a newer Cython that is stricter) is a real compile error, not a transient one.

How to fix it

Declare Cython as a build requirement

pyproject.toml

[build-system]
requires = ["setuptools", "wheel", "Cython>=3.0"]
build-backend = "setuptools.build_meta"

Install the C toolchain too

The generated C still needs a compiler and the Python headers.

Terminal

apt-get update && apt-get install -y build-essential python3-dev
pip install --no-build-isolation Cython
pip install .

Fix the source error

For a CompileError in a .pyx, correct the syntax - this never passes on retry. Pin the language level if a newer Cython changed defaults.

How to prevent it

List Cython in [build-system] requires for .pyx projects.
Pin a Cython major version and a # cython: language_level directive.
Prefer publishing wheels so consumers never run the Cython compile.

Frequently asked questions

What causes Cython "Cython.Compiler.Errors"?

There are 2 common causes: cython missing from the build environment and a genuine cython source error. If the project needs Cython to compile .pyx but does not list it in [build-system] requires, the isolated build env has no Cython and fails.

How do I fix Cython "Cython.Compiler.Errors"?

There are 3 fixes depending on which cause you have: declare cython as a build requirement, install the c toolchain too, and fix the source error. Work through them in order, since the first is the most common.

What does Cython "Cython.Compiler.Errors" actually mean?

A source build fails with a Cython.Compiler.Errors.CompileError, Cython is required to compile, or a C error from generated code.

How do I stop Cython "Cython.Compiler.Errors" happening again?

List Cython in [build-system] requires for .pyx projects. The prevention section lists 3 changes that keep it from recurring.