Author: Kay Hayen


        Nuitka User Manual

.. image:: images/Nuitka-Logo-Symbol.png

.. contents::

.. raw:: pdf

   PageBreak oneColumn
   SetPageCounter 1


Nuitka is the Python compiler. It is a good replacement for the Python
interpreter and compiles **every** construct that CPython 2.6, 2.7, 3.2 and 3.3
offer. It translates the Python into a C++ program that then uses "libpython" to
execute in the same way as CPython does, in a very compatible way.

This document is the recommended first read if you are interested in using
Nuitka, understand its use cases, check what you can expect, license,
requirements, credits, etc.



- C++ Compiler: You need a compiler with support for C++03

  Currently this means, you need to use either of these compilers:

  * GNU g++ compiler of at least version 4.4

  * The clang compiler on MacOS X or FreeBSD, based on LLVM version 3.2

  * The MinGW compiler on Windows

  * Visual Studion 2008 or higher on Windows

- Python: Version 2.6, 2.7 or 3.2, 3.3 (support for upcoming 3.4 exists

  You need the standard Python implementation, called CPython, to execute
  Nuitka, because it is closely tied to using it.

  .. note::

     The created binaries can be made executable independent of the Python
     installation, with ``--standalone`` option.

- Operating System: Linux, FreeBSD, NetBSD, MacOS X, and Windows (32/64 bits),

  Others may work as well. The portability is expected to be generally good, but
  the Scons usage may have to be adapted.

- Architectures: x86, x86_64 (amd64), and arm.

  Other architectures may also work, these are just the only ones
  tested. Feedback is welcome.

Command Line

No environment variable changes are needed, you can call the ``nuitka`` and
``nuitka-run`` scripts directly without any changes to the environment. You may
want to add the ``bin`` directory to your ``PATH`` for your convenience, but
that step is optional.

Nuitka has a ``--help`` option to output what it can do:

.. code-block:: bash

    nuitka --help

The ``nuitka-run`` command is the same as ``nuitka``, but with different
default. It tries to compile and directly execute a Python script:

.. code-block:: bash

    nuitka-run --help

These option that is different is ``--execute``, and passing on arguments after
the first non-option to the created binary, so it is somewhat more similar to
what plain ``python`` will do.


Nuitka is licensed under the Apache License, Version 2.0; you may not use
it except in compliance with the License.

You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied.  See the License for the
specific language governing permissions and limitations under the License.

Use Cases

Use Case 1 - Program compilation with all modules embedded

If you want to compile a whole program recursively, and not only the single file
that is the main program, do it like this:

.. code-block:: bash

    nuitka --recurse-all

.. note::

   The is more fine grained control than ``--recurse-all`` available. Consider
   the output of ``nuitka --help``.

In case you have a plugin directory, i.e. one which is not found by recursing
after normal import statements (recommended way), you can always require that a
given directory shall also be included in the executable:

.. code-block:: bash

    nuitka --recurse-all --recurse-directory=plugin_dir

.. note::

   If you don't do any dynamic imports, simply setting your ``PYTHONPATH`` at
   compilation time will be sufficient for all your needs normally.

   Use ``--recurse-directory`` only if you make ``__import__()`` calls that
   Nuitka cannot predict, because they e.g. depend on command line
   parameters. Nuitka also warns about