Nuitka Organization ORG

Nuitka organization for shared maintenance of Nuitka

20 repos
274 followers
0 following

Python 70%
Jinja 10%
HTML 10%
Shell 10%

.. image:: https://img.shields.io/pypi/pyversions/Nuitka.svg :target: https://pypi.org/project/Nuitka .. image:: https://badge.fury.io/py/Nuitka.svg :target: https://pypi.org/project/Nuitka .. image:: https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg :target: CODE_OF_CONDUCT.md Nuitka User Manual This document is the recommended first read when you start using Nuitka.…

.. image:: https://img.shields.io/pypi/pyversions/Nuitka.svg
:target: https://pypi.org/project/Nuitka

.. image:: https://badge.fury.io/py/Nuitka.svg
:target: https://pypi.org/project/Nuitka

.. image:: https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg
:target: CODE_OF_CONDUCT.md

####################
Nuitka User Manual
####################

This document is the recommended first read when you start using
Nuitka. On this page, you will learn more about Nuitka
fundamentals, such as license type, use cases, requirements, and
credits.

.. contents:: Table of Contents
:depth: 1
:local:
:class: page-toc

Nuitka is the Python compiler. It is written in Python. It is a
seamless replacement or extension to the Python interpreter and compiles
every construct that Python 2 (2.6, 2.7) and Python 3 (3.4 - 3.14)
have, when itself run with that Python version.

It then executes uncompiled code and compiled code together in an
extremely compatible manner.

You can use all Python library modules and all extension modules freely.

Nuitka translates the Python modules into a C level program that then
uses `libpythonand static C files of its own to execute in the same way as CPython does.


All optimization is aimed at avoiding overhead, where it's unnecessary.
None is aimed at removing compatibility, although slight improvements
will occasionally be done, where not every bug of standard Python is
emulated, e.g. more complete error messages are given, but there is a
full compatibility mode to disable even that.
************
 Requirements
**********

To ensure smooth operation of Nuitka, make sure to follow system
requirements, that include the following components:

.. contents::
   :depth: 1
   :local:
C Compiler
==========
You need a C compiler with support for C11 or alternatively a C++
compiler for C++03 [#]_.
Currently, this means, you need to use one of these compilers:

The zig compiler (used with --zig). On Windows, this is
currently limited to compiling for

x64** (AMD64) Python. On other
   platforms, it can be used for all architectures it supports.
The MinGW64 C11 compiler, on Windows. It must be the one Nuitka
   downloads (specify with

--mingw64

), and it enforces that because
   there were frequent breakage with the complete tooling used. It will
   be *automatically* downloaded if no usable C compiler is found, which
   is the recommended way of installing it, as Nuitka will also upgrade
   it for you. But note that MinGW64 does not work with Python 3.13 or
   higher.
Visual Studio 2022 or higher on Windows [#]_. English language pack   for best results (Nuitka filters away garbage outputs, but only for
   English language). It will be used by default if installed.

On all other platforms, the gcc compiler of at least version 5.1,

and below that the g++

 compiler of at least version 4.4 as an
   alternative.

The clang compiler on macOS X and most FreeBSD architectures.

On Windows, the clang-cl compiler on Windows can be used if

   provided by the Visual Studio installer.
.. [#]
Support for this C11 is given with gcc 5.x or higher or any clang
   version.
The older MSVC compilers don't do it yet. But as a workaround, with
   Python 3.10 or older, the C++03 language standard is significantly
   overlapping with C11, it is then used instead.
.. [#]
Download for free from
   https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx
   (the community editions work just fine).
The latest version is recommended, but not required. On the other hand,
   there is no need to except to support pre-Windows 10 versions, and they
   might work for you, but support of these configurations is only
   available to commercial users.
Python
======
Python 2 (2.6, 2.7) and Python 3 (3.4 - 3.14) are supported. If
at any moment, there is a stable Python release that is not in this
list, rest assured it is being worked on and will be added.
.. important::
For Python 3.4 and *only* that version, we need other Python version
   as a *compile time* dependency.
Nuitka itself is fully compatible with all listed versions, but Scons
   as an internally used tool is not.
For these versions, you *need* a Python2 or Python 3.5 or higher
   installed as well, but only during the compile time. That is for use
   with Scons (which orchestrates the C compilation), which does not
   support the same Python versions as Nuitka.

In addition, on Windows, Python2 cannot be used because clcachedoes not work with it, there a Python 3.5 or higher needs to be installed.


Nuitka finds these needed Python versions (e.g. on Windows via
   registry) and you shouldn't notice it as long as they are installed.

Increasingly, other functionality is available when another Python has a certain package installed. For example, onefile compression will work for a Python 2.x when another Python is found that has thezstandard package installed.


.. admonition:: Moving binaries to other machines

The created binaries can be made executable independent of the Python installation, with--mode=standalone and --mode=onefileoptions.


.. admonition:: Binary filename suffix

The created binaries have an .exesuffix on Windows. On other platforms they have no suffix for standalone mode, or.binsuffix, that you are free to remove or change, or specify with the-o option.


The suffix for acceleration mode is added just to be sure that the
   original script name and the binary name do not ever collide, so we
   can safely overwrite the binary without destroying the original
   source file.
.. admonition:: It has to be CPython, Anaconda Python, or Homebrew
You need the standard Python implementation, called "CPython", to
   execute Nuitka because it is closely tied to implementation details
   of it.
.. admonition:: It cannot be from the Windows app store
It is known that Windows app store Python definitely does not work,
   it's checked against.
.. admonition:: It cannot be pyenv on macOS
It is known that macOS "pyenv" does not work. Use Homebrew
   instead for self compiled Python installations. But note that
   standalone mode will be worse on these platforms and not be as
   backward compatible with older macOS versions.
Operating System
================
Supported Operating Systems: Linux, FreeBSD, NetBSD, macOS, and Windows
(32 bits/64 bits/ARM).
Others will work as well. The portability is expected to be generally
good, but the e.g. Nuitka's internal Scons usage may have to be adapted
or need flags passed. Make sure to match Python and C compiler
architecture, or else you will get cryptic error messages.
Architecture
============
Supported Architectures are x86, x86_64 (amd64), and arm, likely many,
many more.
Other architectures are expected to also work, out of the box, as Nuitka
is generally not using any hardware specifics. These are just the ones
tested and known to be good. Feedback is welcome. Generally, the
architectures that Debian supports can be considered good and tested,
too; for example, RISC-V won't pose any issues.
*****
 Usage
*****
Command Line
============

The recommended way of executing Nuitka is -m nuitkato be absolutely certain which Python interpreter you are using, so it is easier to match with what Nuitka has.

The next best way of executing Nuitka bare that is from a source checkout or archive, with no environment variable changes, most noteworthy, you do not have to mess withPYTHONPATHat all for Nuitka. You just execute thenuitka and nuitka-runscripts directly without any changes to the environment. You may want to add thebin directory to your PATHfor your convenience, but that step is optional.

Moreover, if you want to execute with the right interpreter, in that case, be sure to execute bin/nuitka and be good.


.. admonition:: Pick the right Interpreter

If you encounter a SyntaxErroryou absolutely most certainly have picked the wrong interpreter for the program you are compiling.

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


.. code:: bash
nuitka --help

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


.. code:: bash
nuitka-run --help

This option that is different is --run, and passing on arguments after the first non-option to the created binary, so it is somewhat more similar to what plainpython will do.


Installation
============

For most systems, there will be packages on the download page
__ of Nuitka. But you can also install it from source code as described above, but also like any other Python program it can be installed via the normalpython setup.py install routine.

Notice for integration with GitHub workflows there is thisNuitka-Action __ that you should use that makes it really easy to integrate. You ought to start with a local compilation though, but this will be easiest for cross platform compilation with Nuitka.


License
=======
Nuitka is licensed under the GNU Affero General Public License, Version
3; you may not use it except in compliance with the License in
"LICENSE.txt" and the runtime exception granted in
"LICENSE-RUNTIME.txt".
You may obtain a copy of the License at
https://www.gnu.org/licenses/agpl-3.0.html
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.
************************
 Tutorial Setup and Build
**********************

This is basic steps if you have nothing installed, of course if you have
any of the parts, just skip it.
Setup
=====
Install Python
--------------
Download and install Python from
   https://www.python.org/downloads/windows

Select one of Windows x86-64 web-based installer (64 bits Python,
recommended) or x86 executable(32 bits Python) installer.
Verify it's working using command python --version.
Install Nuitka --------------
python -m pip install Nuitka
Verify using command python -m nuitka --version
Write some code and test ======================== Create a folder for the Python code -----------------------------------
mkdir HelloWorld

make a python file named hello.py

.. code:: python
def talk(message):
       return "Talk " + message
def main():
       print(talk("Hello World"))
if __name__ == "__main__":
       main()
Test your program
-----------------
Do as you normally would. Running Nuitka on code that works incorrectly
is not easier to debug.
.. code:: bash
python hello.py
----
Build it using
--------------
.. code:: bash
python -m nuitka hello.py
.. note::

This will prompt you to download a C caching tool (to speed up repeated compilation of generated C code) and a MinGW64 based C compiler, unless you have a suitable MSVC installed. Sayyesto both those questions.
Run it ------
Execute the hello.exe created near hello.py.
Distribute ----------
To distribute, build with --mode=standaloneoption, which will not output a single executable, but a whole folder. Copy the resultinghello.dist folder to the other machine and run it.
You may also try --mode=onefilewhich creates a single executable file. However, we recommend first ensuring your program works correctly with--mode=standalone before using --mode=onefile, as any issues (such as missing data files) are easier to diagnose and fix in standalone mode.

*******
 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:: bash
python -m nuitka --follow-imports program.py
.. note::

There are more fine-grained controls than --follow-importsavailable. Consider the output ofnuitka --help. Including fewer modules into the compilation, but instead using normal Python for it, will make it faster to compile.

In case you have a source directory with dynamically loaded files, i.e. one which cannot be found by recursing after normal import statements via thePYTHONPATH(which would be the recommended way), you can always require that a given directory shall also be included in the executable:


.. code:: bash
python -m nuitka --follow-imports --include-plugin-directory=plugin_dir program.py
.. note::

If you don't do any dynamic imports, simply setting yourPYTHONPATH at compilation time is what you should do.

Use --include-plugin-directory only if you make __import__()calls that Nuitka cannot predict, and that come from a directory, for everything from your Python installation, use--include-moduleor--include-package.


.. note::

The resulting filename will be program.exeon Windows,program.bin on other platforms, but --output-filenameallows changing that.


.. note::
The resulting binary still depends on CPython and used C extension
   modules being installed.

If you want to be able to copy it to another machine, use--mode=standalone and copy the created program.distdirectory and execute theprogram.exe (Windows) or program(other platforms) put inside.


Use Case 2 - Extension Module compilation
=========================================
If you want to compile a single extension module, all you have to do is
this:
.. code:: bash
python -m nuitka --mode=module some_module.py

The resulting file some_module.socan then be used instead ofsome_module.py.


.. important::

The filename of the produced extension module must not be changed as Python insists on a module name derived function as an entry point, in this casePyInit_some_moduleand renaming the file will not change that. Match the filename of the source code to what the binary name should be.


.. note::
If both the extension module and the source code of it are in the
   same directory, the extension module is loaded. Changes to the source
   code only have effect once you recompile.
.. note::

The option --follow-import-toworks as well, but the included modules will only become importable *after* you imported thesome_modulename. If these kinds of imports are invisible to Nuitka, e.g. dynamically created, you can use--include-moduleor--include-packagein that case, but for static imports it should not be needed.


.. note::
An extension module can never include other extension modules. You
   will have to create a wheel for this to be doable.
.. note::
The resulting extension module can only be loaded into a CPython of
   the same version and doesn't include other extension modules.
Use Case 3 - Package compilation
================================
If you need to compile a whole package and embed all modules, that is
also feasible, use Nuitka like this:
.. code:: bash
python -m nuitka --mode=package some_package
.. note::

You can be more specific if you like, and exclude part of it, e.g. with--nofollow-import-to='*.tests'` you would not include the
unused test part of your code.

.. note::

Data files located inside the package will not be embedded by this
process, you need to copy them yourself with

…