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:
- Before you begin
- Step 1: Prepare sample file
- Step 2: Write Python code
- Step 3: Compile Python code using Nuitka
- Step 4: Testing your executable code
- Step 5: Compiling your code to a standalone executable (an independent project)
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
touch sample.py chmod +x sample.py
This step will make sure a file named “sample.py” 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 “sample.py” 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:
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 sample.py 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 sample.py
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, sample.py 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:
If you rather want it to appear in the .bash_profile file:
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 sample.py (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:
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 \ sample.py
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.
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!