Profila: a profiler for Numba

This profiler is sponsored by my book on writing fast low-level code in Python, which uses Numba for most of its examples.

Here's what Profila output looks like:

$ python -m profila annotate -- scripts_for_tests/simple.py
# Total samples: 328 (54.9% non-Numba samples, 1.8% bad samples)

## File `/home/itamarst/devel/profila/scripts_for_tests/simple.py`
Lines 10 to 15:

  0.3% |     for i in range(len(timeseries)):
       |         # This should be the most expensive line:
 38.7% |         result[i] = (7 + timeseries[i] / 9 + (timeseries[i] ** 2) / 7) / 5
       |     for i in range(len(result)):
       |         # This should be cheaper:
  4.3% |         result[i] -= 1

You can also use it with Jupyter!

Beyond this README, you can also read this introductory article with a more detailed example and explanations.

TL;DR limitations: Linux only, and only single-threaded Numba can be profiled currently, parallel functions are not yet supported.

Installation

Currently Profila works on Linux only.

• On macOS you can use Docker, Podman, or a Linux VM.
• On Windows you can use Docker, Podman, or probably WSL2.

Install this library using pip:

pip install profila

Then, have Profila install some dependencies it needs, specifically an older version of gdb; this will not interfere with your system gdb. (This is necessary due to some bad interactions with newer gdb and Numba that will hopefully go away someday.)

python -m profila setup

Usage

Jupyter profiling

First, before you import numba you should:

%load_ext profila

Then define your functions as usual:

from numba import njit

@njit
def myfunc(arr):
    # ... your code here ...

You probably want to call your Numba function at least once, so profiling doesn't measure compilation time:

myfunc(DATA)

Then, you can profile a specific cell using the %%profila magic, e.g.

%%profila
# Make sure we run this enough to get good measurements:
for i in range(100):
    myfunc(DATA)

Command-line profiling

If you usually run your script like this:

$ python yourscript.py --arg1=200

Instead run it like this:

$ python -m profila annotate -- yourscript.py --arg1=200

If you usually run your script like this, with -m:

$ python -m yourpackage --arg1=200

Instead run it like this:

$ python -m profila annotate -- -m yourpackage --arg1=200

Sampling is done every 10 milliseconds, so you need to make sure your Numba code runs for a sufficiently long time. For example, you can run your function in a loop until a number of seconds has passed:

from time import time

@njit
def myfunc():
    # ...

start = time()
# Run for 3 seconds:
while (time() - start) < 3:
    myfunc()

The limitations of profiling output

• Parallel Numba code will not be profiled correctly; at the moment only single-threaded profiling is supported.
• GPU (CUDA) code is not profiled.

Beyond that:

1. The compiled code isn't the same as the input code

Compiled languages like Numba do optimization passes and transform the code to make it faster. That means the running code doesn't necessarily map one to one to the original code; different lines might be combined, for example.

As far as I can tell Numba does give you a reasonable mapping, but you can't assume the source code maps one to one to executed code.

2. Adding the necessary info can change the performance of your code

In order to profile, additional info needs to be added during compilation; specifically, the NUMBA_DEBUGINFO env variable is set. This might change runtime characteristics slightly, because it increases the memory size of the compiled code.

3. Compiled code is impacted by CPU effects that aren't obvious from profiling results

Instruction-level parallelism, branch mispredictions, SIMD, and the CPU memory caches all have a significant impact on runtime performance, but the profiling result doesn't always make it clear that's the problem. I'm writing a book about this if you want to learn more.

Changelog

v0.3.2

• python -m profila setup should now work correctly in Conda environments.
• Support for latest IPython.
• Support for Python 3.13.

v0.3.1

Documentation improvements.

v0.3.0

Bug fixes:

• Work on newer versions of Linux, like Ubuntu 24.04 and RHEL 9, in the face of issues with newer gdb.
• Fixed occasional error TypeError: argument of type 'NoneType' is not iterable.

v0.2.1

Bug fixes:

• Run Python using sys.executable, so it works in more environments. Thanks to Jeremiah England for the bug report.

v0.2.0

Added support for Jupyter profiling.

v0.1.0

Initial release.