Releasing Python's GIL in Cython

Cython's nogil annotation lets you release the Global Interpreter Lock in your code, enabling true parallel execution on multicore CPUs. While pure Python threads are choked by the GIL, Cython nogil code can run on all cores simultaneously. Combine nogil with prange (Cython's parallel loop) and you'll see 4–8× speedups on an octocore machine—genuine multicore parallelism without multiprocessing overhead. This article teaches the nogil syntax and its constraints.

What nogil Does

When you declare a Cython function with cdef and add nogil, the function runs without holding the Global Interpreter Lock. This allows other Python threads to execute simultaneously. Inside a nogil block, you can:

• Call other nogil functions
• Use C types and arrays
• Use compiled NumPy ufuncs

Inside a nogil block, you cannot:

• Create, modify, or reference Python objects (no lists, dicts, strings)
• Call Python functions
• Raise or catch Python exceptions directly

Here's a simple example:

# cython_nogil.pyx
cdef int slow_computation(int n) nogil:
    """A C function that doesn't need the GIL."""
    cdef int result = 0
    cdef int i
    for i in range(n):
        result += i * i
    return result

def compute_wrapper(int n):
    """A Python-callable wrapper that releases the GIL during computation."""
    cdef int res
    with nogil:
        res = slow_computation(n)
    return res

The with nogil: block tells Cython: "Release the GIL, call the nogil function, reacquire the GIL on exit." Other Python threads can now run freely while slow_computation executes.

The with nogil: Pattern

You don't make def functions nogil directly (they need the GIL to interact with Python). Instead, create a cdef nogil helper and call it from a def wrapper:

# matrix_sum.pyx
cdef double sum_matrix_nogil(double[:, :] matrix) nogil:
    """Sum a 2D array without the GIL."""
    cdef int rows = matrix.shape[0]
    cdef int cols = matrix.shape[1]
    cdef double total = 0.0
    cdef int i, j
    
    for i in range(rows):
        for j in range(cols):
            total += matrix[i, j]
    
    return total

def sum_matrix(double[:, :] matrix):
    """Python-callable wrapper that releases the GIL."""
    cdef double result
    with nogil:
        result = sum_matrix_nogil(matrix)
    return result

Call it from Python:

import numpy as np
from matrix_sum import sum_matrix

matrix = np.random.random((1000, 1000))
result = sum_matrix(matrix)
print(result)

While sum_matrix_nogil runs, other Python threads execute—true parallelism.

Parallel Loops with prange

Cython's prange is a parallelized range(). Use it inside a nogil block to split iterations across threads:

# parallel_sum.pyx
from cython.parallel import prange

cdef double sum_array_parallel(double[:] arr) nogil:
    """Sum an array in parallel across CPU cores."""
    cdef int n = arr.shape[0]
    cdef double total = 0.0
    cdef int i
    
    for i in prange(n, nogil=True):
        total += arr[i]
    
    return total

def sum_array(double[:] arr):
    """Python wrapper."""
    cdef double result
    with nogil:
        result = sum_array_parallel(arr)
    return result

Compile with OpenMP support (required for prange):

python setup.py build_ext --inplace

On a 4-core CPU, this parallel version runs ~3.5–4× faster than the sequential version.

Atomic Operations in Parallel Loops

When multiple threads accumulate into the same variable (like total += arr[i]), you need atomic operations to avoid race conditions. Use cython.parallel.atomic:

# atomic_sum.pyx
from cython.parallel import prange
from cython import atomic

cdef double sum_with_atomic(double[:] arr) nogil:
    """Sum using atomic operations to prevent race conditions."""
    cdef int n = arr.shape[0]
    cdef double total = 0.0
    cdef int i
    
    for i in prange(n):
        atomic total += arr[i]
    
    return total

The atomic keyword ensures that total += arr[i] is executed atomically (no two threads interfere). Without it, race conditions corrupt the sum.

Real-World Example: Parallel Matrix Multiply

Here's a practical Cython function for matrix multiplication with the GIL released:

# matmul.pyx
import numpy as np
from cython.parallel import prange

def matmul_parallel(double[:, :] A, double[:, :] B):
    """Multiply two matrices in parallel."""
    cdef int m = A.shape[0]
    cdef int n = A.shape[1]
    cdef int p = B.shape[1]
    cdef double[:, :] C = np.empty((m, p), dtype=np.float64)
    cdef int i, j, k
    cdef double s
    
    for i in prange(m, nogil=True):
        for j in range(p):
            s = 0.0
            for k in range(n):
                s += A[i, k] * B[k, j]
            C[i, j] = s
    
    return np.asarray(C)

Benchmark vs NumPy's single-threaded dot:

import numpy as np
from matmul import matmul_parallel
import timeit

A = np.random.random((500, 500))
B = np.random.random((500, 500))

# Warm up
_ = matmul_parallel(A, B)

t_numba = timeit.timeit(lambda: np.dot(A, B), number=10)
t_cython = timeit.timeit(lambda: matmul_parallel(A, B), number=10)

print(f"NumPy dot: {t_numba:.3f}s")
print(f"Cython parallel: {t_cython:.3f}s")

On a modern CPU with OpenMP:

NumPy dot: 0.234s
Cython parallel: 0.089s

Cython's parallel version is 2.6× faster due to true multicore execution and reduced memory traffic.

Compilation with OpenMP

To use prange and nogil, you must compile with OpenMP (an open-source parallel runtime). In setup.py:

from setuptools import setup
from Cython.Build import cythonize

setup(
    name="parallel_demo",
    ext_modules=cythonize("matmul.pyx", compiler_directives={'language_level': '3'}),
    extra_compile_args=['-fopenmp'],
    extra_link_args=['-fopenmp'],
)

On Windows with MSVC, use:

extra_compile_args=['/openmp']

Comparing Multithreading vs Multiprocessing vs Cython nogil

Method	GIL Held	Speedup (4 cores)	Overhead	Code Complexity
Pure Python threading	Yes	1× (serialized)	Low	Low
multiprocessing	No	3.5–4×	High (process spawning, IPC)	Medium
Cython nogil + prange	No	3.5–4×	Low (thread pool)	High

For data-parallel workloads (matrix ops, image processing), Cython nogil wins: true multicore speedup with low overhead.

Key Takeaways

• Use cdef functions with nogil to create GIL-free code.
• Call nogil functions from def wrappers via with nogil: blocks.
• Replace range() with prange() inside nogil to parallelize loops across cores.
• Use atomic for shared variable updates in parallel loops.
• Compile with OpenMP (-fopenmp) to enable prange.

Frequently Asked Questions

Can I call Python functions from inside a nogil block?

No. Inside nogil, you cannot interact with Python objects or call Python functions. Create a cdef version that does not use Python, and call that.

What happens if I use a Python list inside a nogil function?

Compilation fails with an error: "Cannot access Python attribute in nogil function." Cython prevents this to avoid crashes.

Is nogil faster than multiprocessing?

Yes. nogil avoids process overhead and IPC latency. For tight loops, nogil is 10–100× faster than spawning processes.

What's the overhead of with nogil:?

Acquiring and releasing the GIL is ~10–100 nanoseconds. If your computation takes microseconds or longer, the overhead is negligible. For nanosecond-scale code, the overhead is real.

Can I use nogil with classes?

Not directly. User-defined classes require Python semantics. Use nogil for low-level compute functions; call them from Python classes.

Further Reading

• Cython Parallel Programming (Official Docs)
• Releasing the GIL (Cython Guide)
• OpenMP Directives (OpenMP.org)
• Parallel Computing in Python (Real Python, 2025)