Numba Cheat Sheet

Updated 2026-05-28

Next Topic: NumPy Scientific Computing Cheat Sheet

🧠Study flashcards on this topic121 cards · spaced repetition→

Numba is an open-source just-in-time (JIT) compiler for Python that translates Python functions and NumPy array operations into optimized machine code using the LLVM compiler. Sponsored by Anaconda, Numba specializes in numerical and scientific computing where performance is critical, offering substantial speedups (often 10–100×) with minimal code changes. The key insight is that Numba targets array-oriented numerical code particularly well — loops over NumPy arrays, mathematical computations, and parallel operations that would be slow in pure Python execute at speeds approaching C or Fortran. As of Numba 0.65.x (2026), @jit defaults to nopython mode, the built-in CUDA target is deprecated in favor of the numba-cuda package, and experimental free-threading (Python 3.14t) support has been added.

What This Cheat Sheet Covers

This topic spans 20 focused tables and 191 indexed concepts, 121 flashcards. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.

Table 1: Core JIT DecoratorsTable 2: Compilation Modes and OptionsTable 3: Type Inference and SignaturesTable 4: Parallel Execution PatternsTable 5: NumPy Array OperationsTable 6: CUDA GPU ProgrammingTable 7: Typed ContainersTable 8: Performance OptimizationTable 9: Advanced Decorators and ExtensionsTable 10: Troubleshooting and DebuggingTable 11: Common Limitations and WorkaroundsTable 12: Compilation StrategiesTable 13: Type Specifications for jitclassTable 14: Alternative GPU BackendsTable 15: Random Number GenerationTable 16: Stencil OperationsTable 17: Memory Management and Data TransferTable 18: Interoperability and IntegrationTable 19: Best Practices and Common PatternsTable 20: Version Compatibility

Quick IndexSubscribe to unlock

A jump-to index of every table row in this cheat sheet.

Mind MapSubscribe to unlock

An interactive map of every table and concept in this topic.

Table 1: Core JIT Decorators

The decorator you choose is the most consequential decision when using Numba — it determines compilation mode, target device, and output type. Start with @njit for CPU numerical code, and reach for @vectorize or @cuda.jit only when you specifically need ufuncs or GPU execution.

Decorator	Example	Description
@njit	`@njit` `def f(x):` `return x + 1`	• Alias for @jit(nopython=True) — the recommended default • forces nopython mode and raises error immediately if compilation fails instead of falling back.
@jit	`@jit` `def f(x):` `return x * 2`	• Compiles using lazy JIT compilation (on first call) • since Numba 0.59, defaults to nopython mode (no longer falls back to object mode automatically).
@jit(nopython=True)	`@jit(nopython=True)` `def compute(a, b):` `return a @ b`	• Equivalent to `@njit` • explicit form still widely seen in older code • Redundant since 0.59 but still valid and readable
@jit(signature)	`@jit('float64(float64, float64)')` `def add(x, y):` `return x + y`	• Eager compilation with explicit type signature • compiles immediately at definition time rather than on first call.
@vectorize	`@vectorize(['float64(float64)'])` `def square(x):` `return x ** 2`	• Creates a NumPy universal function (ufunc) from a scalar function • automatically broadcasts over arrays element-wise; supports `cpu`, `parallel`, and `cuda` targets.
@guvectorize	`@guvectorize([(int64[:], int64, int64[:])],` `'(n),()->(n)')` `def g(x, y, res):` `for i in range(x.shape[0]):` `res[i] = x[i] + y`	• Creates a generalized ufunc operating on array segments • layout signature specifies input/output dimensions; supports `writable_args` parameter for in-place modification.
@cuda.jit	`@cuda.jit` `def kernel(arr):` `i = cuda.grid(1)` `if i < arr.size:` `arr[i] *= 2`	• Compiles function as a CUDA GPU kernel (deprecated built-in; install `numba-cuda` package) • launched with `kernel[blocks, threads](args)`.
@cfunc	`@cfunc('float64(float64)')` `def callback(x):` `return x * 2`	• Creates a C-callable function for use as a callback in foreign C/C++ libraries • `.address` gives raw function pointer; `.ctypes` gives ctypes-compatible wrapper.
@stencil	`@stencil` `def smooth(a):` `return (a[-1] + a[0] + a[1]) / 3`	• Defines a neighborhood computation where each output element depends on nearby input elements • automatically determines border handling; combinable with `parallel=True`.
@jitclass	`from numba.experimental import jitclass` `spec = [('value', int64)]` `@jitclass(spec)` `class Counter:` `def __init__(self, v):` `self.value = v`	• Compiles an entire Python class with all methods in nopython mode • requires type spec for fields; now supports static methods and many dunder methods; import from `numba.experimental`.

Table 2: Compilation Modes and Options

These keyword arguments to @jit/@njit control how aggressively Numba compiles, what CPU features it exploits, and how it behaves at runtime. Since Numba 0.59, nopython mode is the default — parallel=True and fastmath=True are the most impactful options for raw throughput.

Option	Example	Description
parallel=True	`@njit(parallel=True)` `def f(a):` `return np.sum(a)`	• Enables automatic parallelization of array operations and `prange()` loops • fuses multiple array ops into single parallel loop; uses native threads (no GIL).

The rest of this section is part of the full cheat sheet

Table 3: Type Inference and Signatures

Numba deduces types automatically on the first call to a JIT-compiled function — you rarely need explicit signatures. Understanding how type inference works helps explain compilation failures and performance differences across input types.

Concept	Example	Description
Lazy type inference	`@njit` `def f(x, y):` `return x + y`	• Automatic type deduction from argument types on first call • each unique combination of argument types triggers a new specialized compilation.

The rest of this section is part of the full cheat sheet

Table 4: Parallel Execution Patterns

Numba's parallel execution model is built on native threads (not the GIL-bound Python threading module), so parallel=True gives genuine multi-core CPU parallelism. The key discipline is ensuring loop iterations are independent before marking them with prange.

Pattern	Example	Description
prange()	`@njit(parallel=True)` `def f(n):` `s = 0` `for i in prange(n):` `s += i * 2` `return s`	• Explicitly parallel range replacing `range()` in loops • iterations must be independent (no cross-iteration dependencies); recognized by Numba as a reduction pattern.

The rest of this section is part of the full cheat sheet

Table 1: Core JIT Decorators

Decorator	Example	Description
@njit	`@njit` `def f(x):` `return x + 1`	• Alias for @jit(nopython=True) — the recommended default • forces nopython mode and raises error immediately if compilation fails instead of falling back.
@jit	`@jit` `def f(x):` `return x * 2`	• Compiles using lazy JIT compilation (on first call) • since Numba 0.59, defaults to nopython mode (no longer falls back to object mode automatically).
@jit(nopython=True)	`@jit(nopython=True)` `def compute(a, b):` `return a @ b`	• Equivalent to `@njit` • explicit form still widely seen in older code • Redundant since 0.59 but still valid and readable
@jit(signature)	`@jit('float64(float64, float64)')` `def add(x, y):` `return x + y`	• Eager compilation with explicit type signature • compiles immediately at definition time rather than on first call.
@vectorize	`@vectorize(['float64(float64)'])` `def square(x):` `return x ** 2`	• Creates a NumPy universal function (ufunc) from a scalar function • automatically broadcasts over arrays element-wise; supports `cpu`, `parallel`, and `cuda` targets.
@guvectorize	`@guvectorize([(int64[:], int64, int64[:])],` `'(n),()->(n)')` `def g(x, y, res):` `for i in range(x.shape[0]):` `res[i] = x[i] + y`	• Creates a generalized ufunc operating on array segments • layout signature specifies input/output dimensions; supports `writable_args` parameter for in-place modification.
@cuda.jit	`@cuda.jit` `def kernel(arr):` `i = cuda.grid(1)` `if i < arr.size:` `arr[i] *= 2`	• Compiles function as a CUDA GPU kernel (deprecated built-in; install `numba-cuda` package) • launched with `kernel[blocks, threads](args)`.
@cfunc	`@cfunc('float64(float64)')` `def callback(x):` `return x * 2`	• Creates a C-callable function for use as a callback in foreign C/C++ libraries • `.address` gives raw function pointer; `.ctypes` gives ctypes-compatible wrapper.
@stencil	`@stencil` `def smooth(a):` `return (a[-1] + a[0] + a[1]) / 3`	• Defines a neighborhood computation where each output element depends on nearby input elements • automatically determines border handling; combinable with `parallel=True`.
@jitclass	`from numba.experimental import jitclass` `spec = [('value', int64)]` `@jitclass(spec)` `class Counter:` `def __init__(self, v):` `self.value = v`	• Compiles an entire Python class with all methods in nopython mode • requires type spec for fields; now supports static methods and many dunder methods; import from `numba.experimental`.

Table 2: Compilation Modes and Options

Option	Example	Description
parallel=True	`@njit(parallel=True)` `def f(a):` `return np.sum(a)`	• Enables automatic parallelization of array operations and `prange()` loops • fuses multiple array ops into single parallel loop; uses native threads (no GIL).

Table 3: Type Inference and Signatures

Concept	Example	Description
Lazy type inference	`@njit` `def f(x, y):` `return x + y`	• Automatic type deduction from argument types on first call • each unique combination of argument types triggers a new specialized compilation.

Table 4: Parallel Execution Patterns

Pattern	Example	Description
prange()	`@njit(parallel=True)` `def f(n):` `s = 0` `for i in prange(n):` `s += i * 2` `return s`	• Explicitly parallel range replacing `range()` in loops • iterations must be independent (no cross-iteration dependencies); recognized by Numba as a reduction pattern.