cli.rst

.. _cli:

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.

.. _cli_usage:

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:
:ref:`numba-source-install-check`.

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.

.. _cli_help:

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


.. _cli_sysinfo:

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)

.. _cli_debug:

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