Command line interface
Numba is a Python package, usually you import numba from Python and use the
Python application programming interface (API). However, Numba also ships with a
command line interface (CLI), i.e. a tool numba that is installed when you
install Numba.
Currently, the only purpose of the CLI is to allow you to quickly show some information about your system and installation, or to quickly get some debugging information for a Python script using Numba.
Usage
To use the Numba CLI from the terminal, use numba followed by the options
and arguments like --help or -s, as explained below.
Sometimes it can happen that you get a “command not found” error when you type
numba, because your PATH isn’t configured properly. In that case you can
use the equivalent command python -m numba. If that still gives “command
not found”, try to import numba as suggested here:
Dependency List.
The two versions numba and python -m numba are the same. The first is
shorter to type, but if you get a “command not found” error because your
PATH doesn’t contain the location where numba is installed, having the
python -m numba variant is useful.
To use the Numba CLI from IPython or Jupyter, use !numba, i.e. prefix the
command with an exclamation mark. This is a general IPython/Jupyter feature to
execute shell commands, it is not available in the regular python terminal.
Help
To see all available options, use numba --help:
$ numba --help
usage: numba [-h] [--annotate] [--dump-llvm] [--dump-optimized]
[--dump-assembly] [--annotate-html ANNOTATE_HTML] [-s]
[--sys-json SYS_JSON]
[filename]
positional arguments:
filename Python source filename
optional arguments:
-h, --help show this help message and exit
--annotate Annotate source
--dump-llvm Print generated llvm assembly
--dump-optimized Dump the optimized llvm assembly
--dump-assembly Dump the LLVM generated assembly
--annotate-html ANNOTATE_HTML
Output source annotation as html
-s, --sysinfo Output system information for bug reporting
--sys-json SYS_JSON Saves the system info dict as a json file
System information
The numba -s (or the equivalent numba --sysinfo) command prints a lot of
information about your system and your Numba installation and relevant
dependencies.
Remember: you can use !numba -s with an exclamation mark to see this
information from IPython or Jupyter.
Example output:
$ numba -s
System info:
--------------------------------------------------------------------------------
__Time Stamp__
Report started (local time) : 2022-11-30 15:40:42.368114
UTC start time : 2022-11-30 15:40:42.368129
Running time (s) : 2.563586
__Hardware Information__
Machine : x86_64
CPU Name : ivybridge
CPU Count : 3
Number of accessible CPUs : ?
List of accessible CPUs cores : ?
CFS Restrictions (CPUs worth of runtime) : None
CPU Features : 64bit aes avx cmov cx16 cx8 f16c
fsgsbase fxsr mmx pclmul popcnt
rdrnd sahf sse sse2 sse3 sse4.1
sse4.2 ssse3 xsave
Memory Total (MB) : 14336
Memory Available (MB) : 11540
__OS Information__
Platform Name : macOS-10.16-x86_64-i386-64bit
Platform Release : 20.6.0
OS Name : Darwin
OS Version : Darwin Kernel Version 20.6.0: Thu Sep 29 20:15:11 PDT 2022; root:xnu-7195.141.42~1/RELEASE_X86_64
OS Specific Version : 10.16 x86_64
Libc Version : ?
__Python Information__
Python Compiler : Clang 14.0.6
Python Implementation : CPython
Python Version : 3.10.8
Python Locale : en_US.UTF-8
__Numba Toolchain Versions__
Numba Version : 0+untagged.gb91eec710
llvmlite Version : 0.40.0dev0+43.g7783803
__LLVM Information__
LLVM Version : 11.1.0
__CUDA Information__
CUDA Device Initialized : False
CUDA Driver Version : ?
CUDA Runtime Version : ?
CUDA NVIDIA Bindings Available : ?
CUDA NVIDIA Bindings In Use : ?
CUDA Detect Output:
None
CUDA Libraries Test Output:
None
__NumPy Information__
NumPy Version : 1.23.4
NumPy Supported SIMD features : ('MMX', 'SSE', 'SSE2', 'SSE3', 'SSSE3', 'SSE41', 'POPCNT', 'SSE42', 'AVX', 'F16C')
NumPy Supported SIMD dispatch : ('SSSE3', 'SSE41', 'POPCNT', 'SSE42', 'AVX', 'F16C', 'FMA3', 'AVX2', 'AVX512F', 'AVX512CD', 'AVX512_KNL', 'AVX512_SKX', 'AVX512_CLX', 'AVX512_CNL', 'AVX512_ICL')
NumPy Supported SIMD baseline : ('SSE', 'SSE2', 'SSE3')
NumPy AVX512_SKX support detected : False
__SVML Information__
SVML State, config.USING_SVML : False
SVML Library Loaded : False
llvmlite Using SVML Patched LLVM : True
SVML Operational : False
__Threading Layer Information__
TBB Threading Layer Available : True
+-->TBB imported successfully.
OpenMP Threading Layer Available : True
+-->Vendor: Intel
Workqueue Threading Layer Available : True
+-->Workqueue imported successfully.
__Numba Environment Variable Information__
None found.
__Conda Information__
Conda Build : not installed
Conda Env : 4.12.0
Conda Platform : osx-64
Conda Python Version : 3.9.12.final.0
Conda Root Writable : True
__Installed Packages__
(output truncated due to length)
Debugging
As shown in the help output above, the numba command includes options that
can help you to debug Numba compiled code.
To try it out, create an example script called myscript.py:
import numba
@numba.jit
def f(x):
return 2 * x
f(42)
and then execute one of the following commands:
$ numba myscript.py --annotate
$ numba myscript.py --annotate-html myscript.html
$ numba myscript.py --dump-llvm
$ numba myscript.py --dump-optimized
$ numba myscript.py --dump-assembly