How to Package Python Apps with PyInstaller: Tips, Encryption, and Docker

Sometimes Python programs need to be packaged into a single folder or file for distribution; as of 2020 the best strategy is to use PyInstaller.

PyInstaller can bundle the entire runtime environment into an executable and supports encryption, but it depends on the external libc.so, which creates two main issues:

Must target older Linux distributions . The libc.so is backward‑compatible (older versions work on newer ones) but not forward‑compatible, so building on a recent distro limits the executable to that version only.

Does not support Alpine . Alpine uses musl libc with a different library path ( /lib/libc.musl‑x86_64.so.1) instead of the standard glibc path ( /lib/x86_64-linux-gnu/libc.so.6), making PyInstaller builds incompatible.

Both problems cannot be solved inside PyInstaller and must be avoided.

Installation

After having a basic Python environment, install PyInstaller:

pip install pyinstaller

CLI entry script

Create a script (e.g., cli.py) that imports the program’s main entry point and runs it:

"""The pyinstaller CLI entry file."""
from foo.__main__ import main

if __name__ == '__main__':
    main()

Other Python programs can use a similar entry.

Encryption

Install with encryption support and provide a 16‑character key at runtime: pip install pyinstaller[encryption] Generate the key using OpenSSL:

openssl rand -base64 16 | cut -c1-16

Full packaging command

python -OO -m PyInstaller -F cli.py --name foo \
    --key=`openssl rand -base64 16 | cut -c1-16`

Using python -m PyInstaller with the -OO flag strips docstrings for a smaller binary.

Dockerfile example

Build the executable in a Debian Stretch image and run it in a minimal Debian Buster (or Ubuntu, CentOS) image, so the runtime does not need Python:

FROM python:3.7-stretch as builder

WORKDIR /opt/code
COPY . /opt/code/
RUN pip install --no-cache-dir pyinstaller \
    && pip install -e . \
    && python -OO -m PyInstaller -F cli.py --name foo \
        --key=`openssl rand -base64 16 | cut -c1-16`

FROM debian:buster-slim

ENTRYPOINT ["foo"]
COPY --from=builder /opt/code/dist/foo /usr/bin/

This approach ensures the runtime image does not contain Python.

References

Using PyInstaller to Easily Distribute Python Applications – Real Python

Substrings in Bash