Nuitka: Compile Python Into a Standalone Executable

Nuitka is a Python compiler that turns your code into a native executable. Its distribution modes let you package an application to run on a compatible machine without a separate Python installation. A more common way to do this is to use a bundler like PyInstaller, which ships your application together with the Python runtime and its dependencies. Nuitka instead compiles your Python code to C before building the executable.

That distinction matters when you’re deciding how to distribute a Python application. Depending on your workload and build mode, Nuitka can offer performance benefits, but they come with trade-offs, including longer build times and additional compiler requirements.

By the end of this tutorial, you’ll understand that:

• Nuitka compiles your Python code to C, while PyInstaller bundles your code with the Python interpreter.
• --mode=standalone produces a folder, --mode=onefile produces a single file that starts more slowly, and --mode=app picks a platform-appropriate format.
• Nuitka’s speedup depends on the workload, and CPU-bound code dominated by Python-level loops benefits the most.
• Nuitka is worth considering when your own benchmarks show a speedup that justifies the C compiler dependency and longer build times.

In this tutorial, you’ll compile a small command-line tool and see where compiling pays off. To follow along, you should be comfortable running Python scripts from the terminal and using a virtual environment. You don’t need any experience with C. Nuitka drives the compiler for you.

Take the Quiz: Test your knowledge with our interactive “Nuitka: Compile Python Into a Standalone Executable” quiz. You’ll receive a score upon completion to help you track your learning progress:

---

Interactive Quiz

Nuitka: Compile Python Into a Standalone Executable

Test your understanding of compiling Python with Nuitka, from standalone and onefile builds to speedups and when PyInstaller fits better.

Getting Started With Nuitka

Before you compile your first Python application, you’ll need Nuitka and a supported C compiler. This tutorial uses Python 3.13.15 for the builds shown below. The compiler setup is discussed later in this section.

You can use uv to create an isolated environment and install Nuitka. If you don’t have uv installed, use the venv and pip alternative described after these steps. Create the environment with uv:

$ uv venv --python 3.13.15

Activate the environment. On macOS and Linux, run the following command:

$ source .venv/bin/activate

In Windows PowerShell, run the following command:

PS> .\.venv\Scripts\Activate.ps1

In the commands below, (.venv) indicates an activated Python virtual environment, whether you created it with venv, uv venv, or another tool.

Then install the version of Nuitka used for this tutorial:

(.venv) $ uv pip install nuitka==4.2.1

Alternatively, create the environment with python -m venv .venv, activate it using the appropriate command above, and install Nuitka with python -m pip install nuitka==4.2.1. The rest of the tutorial uses python -m nuitka, so the build commands work the same way once the environment is activated.

Nuitka uses a C toolchain during compilation, and the compiler setup depends on your operating system. Check the official installation documentation for the current platform-specific requirements.

For this tutorial, you’ll use a small command-line program that counts the most common words in a text file. Save the following code as wordcount.py:

from argparse import ArgumentParser
from collections import Counter
from pathlib import Path

def main():
    parser = ArgumentParser(
        description="Show the most common words in a text file."
    )
    parser.add_argument("file", type=Path)
    parser.add_argument("-n", "--top", type=int, default=5)
    args = parser.parse_args()

    words = args.file.read_text(encoding="utf-8").lower().split()

    for word, count in Counter(words).most_common(args.top):
        print(f"{word}: {count}")

if __name__ == "__main__":
    main()

This script reads a text file, counts word frequency, and prints the most common entries.

Save the following text as sample.txt in the same directory: