PyInstaller: Create An Executable From Python Code

Most will agree that Python is easy to learn and write. When it comes to sharing that beautiful code, there’s one problem, though! Sharing your program with someone that doesn’t know Python is a challenge! Your fellow Pythonistas will be perfectly able to pip install your package or run a Python script you send them. But what about your boss? The non-programmers? This is where PyInstaller comes to play.

PyInstaller bundles your application into a single, runnable file you can share with anyone. No Python installation is required; just click and run! PyInstaller makes life easier for those that want to share their work. This article explains how PyInstaller works and what limitations there are. Finally, we’ll convert a Python program into a runnable file that can be shared with anyone.

How to install PyInstaller

Install PyInstaller in the same virtual environment as your project and its dependencies. That matters: PyInstaller can only bundle the packages that the Python running it can import. The package name you need is pyinstaller, so with the virtual environment activated, a regular pip install would be:

python -m pip install pyinstaller

If you manage your project with uv or Poetry, add it as a development dependency, since your users don’t need it to run your code. With uv, that’s uv add --dev pyinstaller, and you then run it with uv run pyinstaller.

Don’t install PyInstaller as a global tool with uvx or pipx. It runs fine that way, but it won’t see your project’s packages, and your executable fails with a ModuleNotFoundError as soon as it imports one of them.

Supported platforms

PyInstaller officially supports Windows 8 and up, macOS, and Linux, with some limitations you’ll learn about further on.

How PyInstaller works

PyInstaller has two modes:

  1. Single directory mode
  2. one-file mode

The most elegant (in terms of distributing your program) is the one-file mode. It’s a single file, e.g., a .exe on Windows, that you can share with someone. This single file extracts itself into a temporary directory and runs the extracted code. The other mode (single directory) is a directory you can share with someone. It contains your executable, plus a subdirectory called _internal with all the other files it needs.

Let’s dive deeper and see how PyInstaller does its magic.

The Bootloader

PyInstaller creates a so-called bootloader, which bootstraps your Python program. This process is separated from your actual Python program. Hence you can expect to see two processes being launched: first the bootloader and then your own Python code. You don’t have to build the bootloader yourself: PyInstaller ships with prebuilt bootloaders for Windows, macOS and Linux. Only on other platforms, like FreeBSD, does it need to be compiled during installation.

Finding the needed module files

When packaging your Python project, PyInstaller must determine which modules to include. E.g., most software will have at least a couple of import statements, importing either built-in Python modules or externally downloaded modules. PyInstaller analyses your code and finds all the import statements. It does so recursively. For example, if you import a package like the built-in JSON library, it will load the JSON module’s code and analyze any imports found in there. This process repeats until it has all the required files to include.

Some modules do more peculiar things, like using importlib to import other modules. In these cases, you can manually supply pyinstaller the extra modules to include. PyInstaller includes ‘hooks’ for well-known packages that do these things, so chances are you won’t ever need to do this!

Specifying data files

If your software requires data files, you’ll need to tell PyInstaller explicitly. This is done by modifying the so-called spec file PyInstaller creates on the first run. This spec file tells PyInstaller exactly how to process your script. This is an advanced topic, and if you need to do this, I suggest you read the manual page on spec files.

Creating a binary using PyInstaller

Let’s start with an extremely simple use case: a single Python file called hello.py with the following contents:

print("Hello world")Code language: Python (python)

We can use the following command to package our script:

pyinstaller hello.py

After running this command, this is what happens:

  • PyInstaller analyzes your script for any import
  • A hello.spec file is created
  • A build folder is created
  • A dist folder is created, containing a folder called hello

The dist/hello folder contains all the files required to run our program: an executable and an _internal folder with everything else. On Linux and macOS, this executable is called hello, on Windows it will be called hello.exe. This executable file is the bootloader I mentioned before. Run it and see for yourself if it works!

If you check the size of the generated directory, you’ll notice that it’s pretty big for such a small script. When I tried it on a Mac with Python 3.15, it was 19 megabytes, but you need to consider that there’s a lot of overhead. E.g., this dist dir includes a copy of the Python core library, several required libraries, etcetera.

Creating a single file

We’ve used the default settings, creating a directory in dist containing your project. If you want to create a single file, you need to use the -F or --onefile option. I like the latter because it’s easy to remember:

pyinstaller –onefile hello.py

PyInstaller will ask if it may remove the previous output directory, which is OK. Add the -y option if you don’t want it to ask. The output will this time be a single file: hello.exe on Windows or simply hello on Linux and macOS. Run it to verify if everything worked.

Importing external libraries

PyInstaller looks for modules and packages the same way the Python interpreter that runs it does. So if you installed something like requests in your project’s virtual environment, and PyInstaller is installed in that same environment, it will package it with your software just fine. Run PyInstaller from the activated virtual environment, or with uv run pyinstaller in a uv project.

E.g., the following program works flawlessly as long as PyInstaller can find requests:

import requests

print("Hello world")
r = requests.get("https://example.org")
print(r.status_code)
print("Bye")Code language: Python (python)

PyInstaller supports most of the well-known Python libraries out there, including the more advanced ones like:

  • NumPy (which includes a lot of compiled C/C++ code)
  • Pandas
  • Tensorflow
  • Matplotlib
  • PyQT (for GUI programming)
  • Pillow

You can refer to the PyInstaller wiki on GitHub for a more complete list, although this list is not exhaustive. You are encouraged just to try, as most packages will work just fine.

Useful PyInstaller command line options

Here are some more options you might need:

OptionWhat it does
-D, --onedirOutput a directory (the default)
-F, --onefileOutput a single executable file
-n NAME, --name NAMEUse this name for the app, instead of using the script’s basename
--windowedDon’t open a console for standard input and output on Windows and macOS. This option also creates a macOS .app bundle on macOS. Use –icon <file> to specify an icon for the macOS app. This option is ignored on Linux.
--splash <image file>Show a splash image during loading. Only useful in combination with --windowed and for large, slow-loading programs. This is experimental and does not work on macOS.
-i, --icon FILE.icoApply the given icon to the Windows executable file.
A selection of PyInstaller command line options

Limitations

Unfortunately, it’s not all shimmer and shine.

Pyinstaller is not a cross-compiler, which means it can’t create binaries for macOS or Linux from Windows and vice versa. You have to run pyinstaller on each platform that you want to support. E.g., if you want to release your software for both Windows and macOS, you’ll have to build the Windows file on Windows and the macOS file on a macOS machine.

If your software uses external tools and applications, you must add them manually. If these tools are platform specific, you won’t be able to distribute to other platforms unless you find alternative tools that you can include on these other platforms.

Although sharing your code with someone else, using the same OS will work flawlessly most of the time, your mileage may vary when you are on different versions of an OS. If you want to use PyInstaller to distribute your package to many people, you’ll have to put a lot more care into the packaging. The PyInstaller documentation contains more detailed information per OS.

PyInstaller tips and tricks

Here are a few tips and tricks you might need.

Determine if your code is running in a bundle

import sys
if getattr(sys, 'frozen', False) and hasattr(sys, '_MEIPASS'):
    print('running in a PyInstaller bundle')
else:
    print('running in a normal Python process')Code language: Python (python)

Add a splash screen

You can add a splash screen to your bundle, but it is an experimental feature that does not work on macOS. The bootloader shows the splash screen, so the user gets some affirmation that the program is loading/unpacking. You can even display some custom, dynamic text on the splash screen.

To show a splash screen, create an image and specify it with the --splash <image file> option.

Manually add modules that PyInstaller did not recognize

Sometimes PyInstaller does not find all the imports in your code. This can happen when code imports a module by name at runtime, for example with importlib.import_module() or __import__(), so there’s no import statement for PyInstaller to find. You can add the missing libraries manually with the --hidden-import MODULENAME parameter. E.g., to add a missing colorama import, you would use:

pyinstaller --hidden-import colorama myfile.py

To add multiple packages, simply repeat the same option multiple times.

Antivirus warnings

Some antivirus programs, including Windows Defender at times, flag executables made with PyInstaller as suspicious, especially one-file builds. Your code isn’t the problem: malware authors use PyInstaller too, so the bootloader looks familiar to virus scanners. Building in the default one-directory mode, signing your executable, and reporting the false positive to the antivirus vendor all help.

Alternatives to PyInstaller

PyInstaller isn’t the only option. Nuitka compiles your Python code to C and then to an executable, which can make it faster and a bit harder to reverse-engineer. Briefcase, from the BeeWare project, creates proper installers for desktop and mobile platforms.

Learn more about PyInstaller

The PyInstaller documentation is excellent, so I highly recommend you skim through there to see if there’s more that interests you.

Related articles

Leave a Comment