# numba/numba architecture

> Architecture diagram of the GitHub repository numba/numba, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/numba/numba
- Repository: https://github.com/numba/numba

## Overview

Numba is a NumPy-aware just-in-time compiler that turns supported Python numerical functions into machine code, with additional parallel, GPU, ufunc, and C-callback capabilities. The principal workflow starts at the public JIT API, dispatches compilation, analyzes and types code, then lowers it through a target backend to generated code. The graph also preserves documented parallel/GPU and array support. Some compiler-stage links are dashed because the relevant call sites were not sampled; README statements support the major product capabilities.

Main entry points: [`numba/core/compiler.py`](https://github.com/numba/numba/blob/main/numba/core/compiler.py) (Compilation pipeline), [`numba/core/decorators.py`](https://github.com/numba/numba/blob/main/numba/core/decorators.py) (JIT decorators), [`numba/core/dispatcher.py`](https://github.com/numba/numba/blob/main/numba/core/dispatcher.py) (Function dispatcher), [`numba/core/typeinfer.py`](https://github.com/numba/numba/blob/main/numba/core/typeinfer.py) (Type inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_jit_api["JIT decorators<br/>[decorators.py]"]
  node_dispatcher["Function dispatcher<br/>[dispatcher.py]"]
  node_c_callbacks["C callbacks<br/>[ccallback.py]"]
end

subgraph group_compiler["Compiler Core"]
  node_compiler["Compilation pipeline<br/>[compiler.py]"]
  node_bytecode["Bytecode analysis<br/>[bytecode.py]"]
  node_ir["Intermediate representation<br/>[ir.py]"]
  node_typing["Type inference<br/>[typeinfer.py]"]
  node_typing_rules["Typing rules<br/>[collections.py]"]
  node_types["Type system<br/>[abstract.py]"]
end

subgraph group_backend["Code Generation"]
  node_lowering["Native lowering<br/>[lowering.py]"]
  node_llvm_codegen["LLVM code generation<br/>[codegen.py]"]
end

subgraph group_numerics["Numerical Features"]
  node_numpy_arrays["NumPy arrays<br/>[arrayobj.py]"]
  node_numpy_mapping["NumPy type support<br/>[numpy_support.py]"]
  node_parallel["Loop parallelization<br/>[parfor.py]"]
  node_ufunc["Ufunc creation<br/>[ufuncbuilder.py]"]
end

subgraph group_accelerators["Accelerators"]
  node_cuda_api["CUDA API<br/>[api.py]"]
  node_cuda_compile["CUDA compilation<br/>[compiler.py]"]
  node_cuda_driver["CUDA device driver<br/>[driver.py]"]
end

node_user(("Python developer"))

node_user -->|"decorates function"| node_jit_api
node_jit_api -.->|"creates dispatcher"| node_dispatcher
node_dispatcher -.->|"requests compilation"| node_compiler
node_compiler -.->|"analyzes bytecode"| node_bytecode
node_compiler -.->|"builds IR"| node_ir
node_compiler -.->|"infers types"| node_typing
node_typing -.->|"resolves operations"| node_typing_rules
node_typing_rules -->|"uses types"| node_types
node_compiler -.->|"lowers code"| node_lowering
node_lowering -.->|"emits LLVM"| node_llvm_codegen
node_user -->|"launches kernels"| node_cuda_api
node_cuda_api -.->|"compiles kernels"| node_cuda_compile
node_cuda_compile -.->|"uses device driver"| node_cuda_driver
node_user -->|"parallelizes loops"| node_parallel
node_user -->|"creates ufuncs"| node_ufunc
node_user -->|"creates callbacks"| node_c_callbacks
node_numpy_arrays -->|"uses type support"| node_numpy_mapping
node_compiler -.->|"supports parallel loops"| node_parallel

click node_jit_api "https://github.com/numba/numba/blob/main/numba/core/decorators.py"
click node_dispatcher "https://github.com/numba/numba/blob/main/numba/core/dispatcher.py"
click node_compiler "https://github.com/numba/numba/blob/main/numba/core/compiler.py"
click node_bytecode "https://github.com/numba/numba/blob/main/numba/core/bytecode.py"
click node_ir "https://github.com/numba/numba/blob/main/numba/core/ir.py"
click node_typing "https://github.com/numba/numba/blob/main/numba/core/typeinfer.py"
click node_typing_rules "https://github.com/numba/numba/blob/main/numba/core/typing/collections.py"
click node_types "https://github.com/numba/numba/blob/main/numba/core/types/abstract.py"
click node_lowering "https://github.com/numba/numba/blob/main/numba/core/lowering.py"
click node_llvm_codegen "https://github.com/numba/numba/blob/main/numba/core/codegen.py"
click node_numpy_arrays "https://github.com/numba/numba/blob/main/numba/np/arrayobj.py"
click node_numpy_mapping "https://github.com/numba/numba/blob/main/numba/np/numpy_support.py"
click node_parallel "https://github.com/numba/numba/blob/main/numba/parfors/parfor.py"
click node_ufunc "https://github.com/numba/numba/blob/main/numba/np/ufunc/ufuncbuilder.py"
click node_cuda_api "https://github.com/numba/numba/blob/main/numba/cuda/api.py"
click node_cuda_compile "https://github.com/numba/numba/blob/main/numba/cuda/compiler.py"
click node_cuda_driver "https://github.com/numba/numba/blob/main/numba/cuda/cudadrv/driver.py"
click node_c_callbacks "https://github.com/numba/numba/blob/main/numba/core/ccallback.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_jit_api,node_dispatcher,node_c_callbacks toneBlue
class node_compiler,node_bytecode,node_ir,node_typing,node_typing_rules,node_types toneAmber
class node_lowering,node_llvm_codegen toneMint
class node_numpy_arrays,node_numpy_mapping,node_parallel,node_ufunc toneRose
class node_cuda_api,node_cuda_compile,node_cuda_driver,node_user toneIndigo
```

## Components

### Public API

- [JIT decorators](https://github.com/numba/numba/blob/main/numba/core/decorators.py): `numba/core/decorators.py`
- [Function dispatcher](https://github.com/numba/numba/blob/main/numba/core/dispatcher.py): `numba/core/dispatcher.py`
- [C callbacks](https://github.com/numba/numba/blob/main/numba/core/ccallback.py): `numba/core/ccallback.py`

### Compiler Core

- [Compilation pipeline](https://github.com/numba/numba/blob/main/numba/core/compiler.py): `numba/core/compiler.py`
- [Bytecode analysis](https://github.com/numba/numba/blob/main/numba/core/bytecode.py): `numba/core/bytecode.py`
- [Intermediate representation](https://github.com/numba/numba/blob/main/numba/core/ir.py): `numba/core/ir.py`
- [Type inference](https://github.com/numba/numba/blob/main/numba/core/typeinfer.py): `numba/core/typeinfer.py`
- [Typing rules](https://github.com/numba/numba/blob/main/numba/core/typing/collections.py): `numba/core/typing/collections.py`
- [Type system](https://github.com/numba/numba/blob/main/numba/core/types/abstract.py): `numba/core/types/abstract.py`

### Code Generation

- [Native lowering](https://github.com/numba/numba/blob/main/numba/core/lowering.py): `numba/core/lowering.py`
- [LLVM code generation](https://github.com/numba/numba/blob/main/numba/core/codegen.py): `numba/core/codegen.py`

### Numerical Features

- [NumPy arrays](https://github.com/numba/numba/blob/main/numba/np/arrayobj.py): `numba/np/arrayobj.py`
- [NumPy type support](https://github.com/numba/numba/blob/main/numba/np/numpy_support.py): `numba/np/numpy_support.py`
- [Loop parallelization](https://github.com/numba/numba/blob/main/numba/parfors/parfor.py): `numba/parfors/parfor.py`
- [Ufunc creation](https://github.com/numba/numba/blob/main/numba/np/ufunc/ufuncbuilder.py): `numba/np/ufunc/ufuncbuilder.py`

### Accelerators

- [CUDA API](https://github.com/numba/numba/blob/main/numba/cuda/api.py): `numba/cuda/api.py`
- [CUDA compilation](https://github.com/numba/numba/blob/main/numba/cuda/compiler.py): `numba/cuda/compiler.py`
- [CUDA device driver](https://github.com/numba/numba/blob/main/numba/cuda/cudadrv/driver.py): `numba/cuda/cudadrv/driver.py`

### Other components

- **Python developer**

## Connections

- Python developer → JIT decorators: decorates function
- JIT decorators → Function dispatcher: creates dispatcher
- Function dispatcher → Compilation pipeline: requests compilation
- Compilation pipeline → Bytecode analysis: analyzes bytecode
- Compilation pipeline → Intermediate representation: builds IR
- Compilation pipeline → Type inference: infers types
- Type inference → Typing rules: resolves operations
- Typing rules → Type system: uses types (evidence: `numba/core/typing/collections.py`)
- Compilation pipeline → Native lowering: lowers code
- Native lowering → LLVM code generation: emits LLVM
- Python developer → CUDA API: launches kernels
- CUDA API → CUDA compilation: compiles kernels
- CUDA compilation → CUDA device driver: uses device driver
- Python developer → Loop parallelization: parallelizes loops
- Python developer → Ufunc creation: creates ufuncs
- Python developer → C callbacks: creates callbacks
- NumPy arrays → NumPy type support: uses type support (evidence: `numba/np/arrayobj.py`)
- Compilation pipeline → Loop parallelization: supports parallel loops
