Numba: High Performance Python Compiler

0.64.0 verified Tue May 12 auth: no python install: draft quickstart: draft

Numba is an open-source, NumPy-aware optimizing Just-In-Time (JIT) compiler for Python. It translates a subset of Python and NumPy code into fast machine code using the LLVM compiler library, enabling numerical algorithms to approach the speeds of C or Fortran without requiring a separate compilation step. Numba is currently at version 0.64.0 and maintains a regular release cadence, often coinciding with Python and NumPy releases.

pip install numba

Common errors

error ModuleNotFoundError: No module named 'numba' ↓

cause Numba is not installed in the currently active Python environment, or there is a mismatch between the Python interpreter used for installation and the one used for execution.

fix

Ensure Numba is installed in your active environment using pip install numba or conda install numba. Verify the Python executable by checking which python and which pip (or where python and where pip on Windows) to ensure they belong to the same environment. If using Jupyter/IPython, restart the kernel after installation.

error TypeError: No matching definition for argument type(s) ↓

cause Numba, especially in `nopython` mode, failed to infer the types of arguments or found an operation between types that it does not support, preventing compilation to native code.

fix

Inspect the types of variables within the jitted function using my_jitted_func.inspect_types(). Ensure all operations and data types are supported by Numba (consult Numba documentation for supported features). Often, this means avoiding dynamic Python features like heterogeneous lists or unsupported object methods. Consider explicitly casting types where Numba's inference struggles, or refactoring code to use NumPy arrays and operations. If this occurs in an IDE like Spyder, try adding numba to the UMR excluded modules in preferences and restarting the console.

error NumbaWarning: Function "..." was compiled in object mode without forceobj=True. Fall-back from the nopython compilation path to the object mode compilation path has been detected, this is deprecated behaviour. ↓

cause Numba attempted to compile the function in `nopython` mode but encountered Python features or types it could not translate to machine code. It then silently fell back to 'object mode', which offers little to no performance improvement over regular Python.

fix

To achieve performance benefits, compilation must succeed in nopython mode. Explicitly use @numba.njit (which is shorthand for @numba.jit(nopython=True)) to force nopython mode. This will raise an error instead of silently falling back, giving specific details about what Numba cannot compile. Refactor the problematic parts of the code to use Numba-supported types and operations. Use my_jitted_func.inspect_types() to see which variables are typed as pyobject, indicating areas that prevented nopython compilation.

error This error is usually caused by passing an argument of a type that is unsupported by the named function. ↓

cause This specific message indicates that Numba's type inference could not resolve an operation (e.g., a function call or arithmetic operation) because one or more arguments had a type that the operation does not support within Numba's compilation context, particularly in `nopython` mode.

fix

Identify the line of code and the specific operation/function call mentioned in the full traceback. Examine the types of the arguments being passed to that operation. Ensure that the types are primitive (e.g., int, float), NumPy arrays, or other Numba-supported types, and that the operation is valid for those types within Numba. Avoid passing Python objects, lists, or dictionaries unless specifically supported by Numba for that operation. Consider explicitly defining function signatures or local variable types if inference is failing.

Warnings

gotcha Numba treats global variables as compile-time constants. Modifying a global variable after a `@jit` decorated function has been compiled will not affect the compiled function's behavior unless the function is explicitly recompiled using `.recompile()` or the global is passed as an argument. ↓

fix Either recompile the function after modifying the global variable or, preferably, refactor your code to pass the variable as an argument to the jitted function.

gotcha Type inference failures are a common reason for Numba compilation errors, especially in `nopython` mode. Numba needs to determine concrete types for all variables; if it cannot, compilation will fail. ↓

fix Ensure that all operations and data types within a `@njit` (nopython mode) function are supported by Numba and that types are consistent. Explicitly casting types (e.g., using `np.int64(0)` instead of `0`) can sometimes help with type propagation.

gotcha Running Numba-compiled scripts twice in IDEs like Spyder can lead to `TypeError: No matching definition for argument type(s)` due to module reloading issues. ↓

fix Configure Spyder to exclude `numba` from its User Module Reloader (UMR). Go to `Preferences -> Console -> Advanced Settings`, click 'Set UMR excluded modules', and add `numba`. Restart the IPython console after applying the setting.

deprecated The `target` kwarg for the `numba.jit` decorator family has been deprecated. ↓

fix Avoid using the `target` kwarg. Numba's decorators like `jit` and `njit` infer the target (CPU by default) or specific GPU decorators like `cuda.jit` should be used for explicit targets.

deprecated Reflection for Python `List` and `Set` types within Numba-compiled code is deprecated. This feature ensured changes to mutable Python containers were visible after the function returned. ↓

fix Numba aims to replace this with a better implementation. Users relying on reflection for these types might need to adapt their code if they observe unexpected behavior or warnings in future versions. Pinning Numba dependency is recommended if relying on this behavior.

breaking Numba 0.64.0 supports NumPy 2.3 and 2.4. NumPy 2.0 introduces binary incompatible changes and a new type system. Numba has evolved to accommodate this, but users should be prepared to test and verify their codebases, as NumPy 2.0 may also impact non-JIT compiled code output. ↓

fix Update to Numba 0.64.0 or later to ensure compatibility with NumPy 2.x. Review Numba's documentation and NumPy 2.0 migration guides for potential code adjustments, especially concerning type interactions.

breaking The experimental RVSDG (Region-based Value Stream Dependence Graph) frontend was removed in Numba 0.61.0. ↓

fix Code relying on the experimental RVSDG frontend will no longer function. Users should remove any explicit enabling of this frontend from their Numba configurations.

breaking Building Numba and its dependencies (like llvmlite) requires system-level development tools such as a C compiler (e.g., GCC) and CMake. These tools are often not included in minimal base images or environments (e.g., Alpine Linux) by default. ↓

fix Ensure that the necessary build tools are installed in your environment. For Debian-based systems, use `apt-get install build-essential cmake`. For Alpine Linux, use `apk add build-base cmake`. For other operating systems, consult their documentation for installing development tools and CMake.

Install

conda install numba

Install compatibility draft last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - 0.96s 274M

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - 1.01s 288M

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - 1.05s 275M

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - 1.03s 274M

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - 0.92s 251M

Imports

jit
wrong
```
import numba.jit
```
correct
```
from numba import jit
```
`jit` is typically imported directly from the `numba` package as a decorator, not as a submodule.
njit
```
from numba import njit
```
`njit` is a shorthand for `@jit(nopython=True)`, ensuring Numba generates code that doesn't fall back to the Python interpreter, which is often desired for performance.
guvectorize
```
from numba import guvectorize
```

Quickstart draft last tested: 2026-04-23

This quickstart demonstrates the core usage of Numba's `@njit` decorator to compile a Python function for numerical computation. The function `sum_array` iterates over a NumPy array, and when decorated with `@njit`, Numba compiles it to highly optimized machine code at runtime, significantly speeding up its execution compared to pure Python.

import numpy as np
from numba import njit

@njit
def sum_array(arr):
    total = 0.0
    for x in arr:
        total += x
    return total

# Example usage
data = np.arange(1000000, dtype=np.float64)
result = sum_array(data)
print(f"Sum of array: {result}")