numba

Numba Best Practices

Numba is your go-to for accelerating numerical Python. Follow these rules to ensure your JIT-compiled code is fast, correct, and maintainable.

Code Organization and Structure

Isolate Numba-jitted code in dedicated modules.

Keep your Numba-accelerated functions separate from general Python logic. This creates clear boundaries, simplifies debugging, and prevents accidental object mode fallbacks.

❌ BAD: Mixing Numba with high-level logic

import numba
import numpy as np
import pandas as pd

@numba.njit
def process_array(data):
    # Numba-optimized part
    return np.sqrt(data) * 2

def analyze_data(df: pd.DataFrame):
    # High-level Python logic, potentially calling Numba functions
    processed = process_array(df['value'].to_numpy())
    return pd.DataFrame({'processed': processed})

✅ GOOD: Dedicated module for accelerated functions

# my_project/accelerated_math.py
import numba
import numpy as np

@numba.njit(fastmath=True, parallel=True)
def process_array(data: np.ndarray) -> np.ndarray:
    """Applies a numerical transformation to a NumPy array."""
    return np.sqrt(data) * 2

# my_project/data_analysis.py
import pandas as pd
from my_project.accelerated_math import process_array

def analyze_data(df: pd.DataFrame):
    processed_data = process_array(df['value'].to_numpy())
    return pd.DataFrame({'processed': processed_data})

Common Patterns and Anti-patterns

Always use @njit for CPU acceleration.

@njit (an alias for @jit(nopython=True)) forces Numba to compile your function entirely without the Python interpreter. If Numba cannot do this, it will raise an error, preventing silent performance degradation.

❌ BAD: Using @jit without nopython=True

from numba import jit
import numpy as np

@jit # Could silently fall back to object mode, making it slow
def slow_sum(arr):
    total = 0
    for x in arr: # If 'x' becomes a Python object, this is slow
        total += x
    return total