Compiling Python to standalone executables on Linux using Nuitka

Your Python programs are portable to multiple operating systems, but some end users simply do not want to take the time to install and set up a complete Python system just to run your project code.

If you are a Python programmer, it is likely that you recognise this situation, and at some point you thought: “why is this not possible?” Well, it is possible! Enter the world of Nuitka, a Python to C++ code compiler! You can download it from the official site right here. Just press the Download link and choose the operating system you want to compile your project on.

In this HOWTO we will be creating a Python program and then packaging it up using Nuitka into an executable for easy installation by users.

Table of Contents:

Nuitka Python compilation HOWTO

Now it is time to show you how to compile a Python application. Let us begin by creating a sample application. You can use this code freely and modify it any way you want.

Note: we are going to use Ubuntu Linux 15.04 in this how-to tutorial, so if you want to repeat the steps straight off, I recommend you use Ubuntu (or any Linux system with all necessary Python 3 packages and dependencies installed).

Important information before you begin

Download the package that corresponds to the operating system you are using.

If you want to compile the project as a Windows executable file (.exe), choose to download the Windows version of Nuitka and compile it.

If you want a Linux version compiled, make sure you use the Linux version of Nuitka and compile it by launching a command-line interface, like Terminal in Ubuntu, xterm, aterm or use ssh remote login from another machine of your choice.

What about OS X and Mac support? It does work on Mac computers, but if Nuitka complains that you are missing a Tcl/Tk framework in your OS X system, you need to install or compile that before Nuitka can compile the Python project for you.

Binary install packages of ActiveTCL for multiple operating systems

Do you want to save time and effort by installing binary versions instead of compiling it on your own? There is a free community edition available at the ActiveTCL website right here.

Step 1: Prepare a sample file

chmod +x

This step will make sure a file named “” will be created using the UNIX/Linux touch command. Then, the chmod command will add permission to execute (run) the Python code as a normal executable file would be run.

Step 2: Provide some programming code


By running the above command in step 2, a Linux command-line editor will be presented on your screen. The file named “” will open and it should be empty. Now, either copy-paste the code below or type in each row by hand, manually.

Source code is provided below:

#!/usr/bin/env python3
# coding: utf-8
print('Hello user.')

Now, just run it to make sure it works:


The output should be the following:

Hello user.

If you see the above output, “Hello user.”, everything worked as expected. The next step is to initiate Nuitka to compile it.

Step 3a: Compiling using Nuitka

Make sure you have installed Nuitka first, by downloading the latest package from the official website here.

To compile your project, open up a terminal window in Linux. Where did you put your project file called which we created in step 2? Find that directory first. Once you have navigated to that directory, type the following:

nuitka --recurse-on --python-version=3.4

There are two things you should be aware of right now.

The first is the “–recurse-on” optional command-line argument. The provided argument makes sure to compile in any modules you might have imported into your Python application. In this particular case, does not include any imports, so we are good to go without using that argument. However, it is nice to include it anyway for any future application you want to use it for.

The second thing to notice is the “–python-version” argument. In this case, I am relying on Python version 3.4 to be installed in my system when trying to compile the code with Nuitka. You can change this to any version you have installed and need to compile the code with. If you do not provide the python version argument, it will likely default to Python version 2, so keep that in mind.

Step 3b: Creating an alias for Nuitka

If you want to make an alias for this, just type in the following command in your Linux terminal:

alias nuitka="nuitka --recurse-all --python-version=3.4"

Important: this alias will not be saved once you close the terminal. To enable it for every new launching of a terminal, you need to place it somewhere convenient in your system, such as $HOME/.profile or $HOME/.bash_profile in your Linux system. Just open up an editor like nano and add it in, on a new line at the very end of the file:

nano $HOME/.profile

If you rather want it to appear in the .bash_profile file:

nano $HOME/.bash_profile

If you want to be reminded that the alias is active, add this command as well, either before or after the alias command:

echo "Enabling nuitka alias ... done."

This echo line will notify you on every login session via a terminal that you have this alias enabled. You do not need it whatsoever and the text can say anything you want it to say. However, I use it to make sure I always know that the nuitka command can be run without additional argument options on every Python project compilation.

Step 4: Testing your executable code

There should be a file in your current directory called (the one we created just moments ago) and a new executable file called sample.exe which, although confusingly similarly named as if it were a Windows executable, it is a normal Linux executable binary. If you want to name it something else, just rename it:

mv sample.exe sample

At this point, you have an executable file named “sample” which you can run right away:


You should get the same message as before:

Hello user.

If so, everything works fine. Congratulations! You have now learned the basics in compiling Python code to C++ code. There is one final thing to note: you have now created C++ code which has been compiled into native machine code, which can be run on your system. However, you still need to have Python installed in order to run it.

Step 5: Compiling your code to a standalone, independent project

Okay, so you want to have a standalone project where Python is not needed to make the program run? Just modify your alias. Run this command:

nuitka --standalone --recurse-on --python-version=3.4 \

Notice the new argument here, “–standalone”. It will make sure that your project bundles everything you need.

Where did the files go after you compiled them as a standalone project? You are going to notice a new directory being added into your current directory called sample.dist where both your sample.exe and any necessary files relating to the executable file will be located. If you want to distribute those files, you could add them to a zip file or any other archive file format of choice. If you want to, you can rename the project to something more interesting than “sample.exe” and “sample.dist”.

As a result, the project will grow significantly in size as well. On my system, the sample.exe file is 7.1 megabytes in size and the project directory as a whole is 31 megabytes in size. This can be compared to the 88 kilobytes (!) in size that the non-standalone “sample.exe” file occupies when I compile the project without the standalone argument.

In conclusion

Python is great. It is portable and easy to learn. It is popular and widely used around the world. However, for those occasions where you want to distribute your project in a nice, independent and convenient binary environment, Nuitka really comes in handy. Just make sure you download Nuitka for each system you want to compile it for.

You will then end up having several binary versions of your Python code that will run independently, without the need for users to install Python alongside your own project files. Good luck!


  1. thank you! very informative. i only had one issue when compiling standalone. my terminal gave me several lines the read the following.
    Nuitka:WARNING:Unresolved ‘__import__’ call at ‘/usr/lib/python2.7/’ may require use of ‘–recurse-directory’.

  2. I compiled a TwitterBot I had created with python that works great. To be honest I never thought it work. Other than the exe file, it only requires the twitter API key, and that was exterior because I wanted to use various keys. Also my font is also an exterior file, again my choice. It chooses random image files from a subdirectory Titles and Signs the image and posts it to Twitter I love Nuitka.

  3. Hi, why nuikta does not import numpy and opencv Cannot find ‘cv2’ as absolute import. Cannot find ‘numpy’ as absolute import.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.