How to package Python programs into binaries on Raspberry Pi 4B?

Newbie Guide Basic Q&A
, ,
1

I am unable to install PyInstaller. Is there any other way to package Python files into binary executables on a Raspberry Pi?

2

PyInstaller can be installed using pip:

pip install pyinstaller

Reference: https://www.cnblogs.com/wendaobiancheng/p/9772509.html

3

Using this command will result in this error, and the installation will not succeed.

pip install pyinstaller
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
python3-xyz, where xyz is the package you are trying to
install.

If you wish to install a non-Debian-packaged Python package,
create a virtual environment using python3 -m venv path/to/venv.
Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
sure you have python3-full installed.

For more information visit http://rptl.io/venv

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.
4

Using this command: sudo apt install python3-pyinstaller

The corresponding installation package cannot be found.
Reading package lists… Done
Building dependency tree… Done
Reading state information… Done
E: Unable to locate package python3-pyinstaller

5

https://www.cnblogs.com/clark1990/p/17942952

It is recommended to install using pipx.

6

On Raspberry Pi (Raspberry Pi 4B), if you’re unable to use PyInstaller, the most powerful alternative is Nuitka. Unlike PyInstaller, which merely “packages” your code, Nuitka converts your Python code into C code and compiles it into a true machine-code binary.

Here are several common methods for packaging Python applications into binaries on Raspberry Pi:

1. Nuitka (Highly Recommended: High Performance, True Compilation)

Nuitka is a very popular packaging tool in the Python community, especially suitable for Linux environments like the Raspberry Pi. The generated binaries typically run faster than native Python.

Installation Steps:

  1. First, install the necessary C compiler (usually pre-installed on Raspberry Pi, but it’s recommended to update):
sudo apt update
sudo apt install build-essential python3-dev
  1. Install Nuitka:
pip install nuitka

Packaging Command:

Run the following command in your project directory:

python3 -m nuitka --standalone --onefile --remove-output your_script.py
  • --standalone: Includes all dependency libraries.
  • --onefile: Bundles everything into a single executable file.
  • --remove-output: Removes the temporary folder containing generated C code after compilation.

2. cx_Freeze (Mature and Stable Alternative)

If you find Nuitka’s compilation time too long (due to its complex optimizations), cx_Freeze is a more PyInstaller-like option.

Installation Steps:

pip install cx_Freeze

Usage:

Create a file named setup.py:

from cx_Freeze import setup, Executable

setup(
    name = "My Application",
    version = "1.0",
    description = "Description",
    executables = [Executable("your_script.py")]
)

Then run in the terminal:

python3 setup.py build

This will generate a folder under the build directory containing the executable and its dependencies.

3. Shiv (Zipapp Approach: Lightweight)

If your goal is simply “single-file distribution” rather than strict “obfuscation/machine-code binary,” Shiv is an excellent choice. It leverages Python’s built-in zipapp functionality.

Usage:

pip install shiv
shiv -e your_module.main -o my_app .

It compresses your code and all dependencies into a large .pyz file (on Linux, you can directly make it executable with chmod +x my_app && ./my_app). Advantages include extremely fast packaging and high stability.

4. Why Can’t PyInstaller Be Installed? (Common Fixes)

PyInstaller installation often fails on Raspberry Pi due to missing binutils or Python development libraries. If you’d like to try again, first run:

sudo apt install python3-dev binutils libffi-dev
pip install pyinstaller

If the error message contains references to arm-linux-gnueabihf-gcc, you’re likely missing build-essential.

Comparison of Solutions

Tool Principle Advantages Disadvantages
Nuitka Compiles to C code Fast execution, hard to reverse-engineer, true binary Long compilation time, may require debugging for complex libraries
cx_Freeze Environment freezing Flexible configuration, good cross-platform support Outputs a folder (unless combined with AppImage)
Shiv Zipapp archive 100% library compatibility, extremely fast packaging Target machine must have Python interpreter installed

Recommendation:
Use Nuitka if you prioritize security and performance; use Shiv if you want fast packaging and don’t mind whether the target machine has a Python environment.