Posted inPython

Convert Python Scripts into Professional .exe Files with PyInstaller: An A-Z Guide

Python tutorial - IT technology blog
Python tutorial - IT technology blog

How do you get your boss or colleagues to run your Python script?

You’ve just finished a great data scraping bot that automates a ton of manual work. But when you send the .py file to your boss, you get: “I don’t have Python installed, how do I run this?”. At that point, surely you won’t sit there installing the environment and running pip install on every machine in the office?

That’s why we need packaging. Believe me, turning your code into a single .exe (Windows) or .app (macOS) file makes you look much more professional. Users just need to “double click” to run it—simple and clean.

Should you choose PyInstaller, Nuitka, or cx_Freeze?

In reality, there are 3 standout names I’ve experienced:

  • PyInstaller: The “go-to” in the Python world. It bundles everything (interpreter, libraries) into one package. Its biggest plus is being extremely easy to use with a massive support community.
  • Nuitka: For those who want optimization. It compiles code to C++ before creating the executable. Your code is harder to reverse-engineer, but the trade-off is very long build times.
  • cx_Freeze: A middle-ground option with decent cross-platform support, but the documentation can sometimes be outdated compared to the big two.

My advice: Start with PyInstaller. It’s stable and covers 90% of practical needs.

Pros and Cons: Don’t expect too much!

Before typing any commands, you should know that PyInstaller isn’t a magic wand.

Pros

  • Convenience: Sometimes just one command is enough to get the final product.
  • One-file Mode: Compresses everything into exactly one file. Perfect for quick sharing via Zalo or Telegram.
  • Smart: It automatically scans your code to see if you’re using pandas or requests and pulls them along; no manual declaration needed.

Cons

  • Hefty File Size: A 1KB “Hello World” script can weigh up to 12MB after packaging. If you use pandas, the file can easily jump to 300MB.
  • Slower Startup: In one-file mode, the computer takes about 2-3 seconds to extract files into a temporary folder before executing the code.
  • Antivirus Flags: Due to the mechanism of extracting files into the Temp folder, some software like Windows Defender might falsely flag it as a virus.

Detailed Implementation Guide

Let’s assume we have a file named my_tool.py that needs to be sent to a client.

Step 1: Never use the Global environment

The biggest mistake beginners make is installing PyInstaller directly into the system. It will pull in tons of unrelated junk libraries, making the exe file unnecessarily heavy. Use a Virtual Environment instead:

# Create and activate virtual environment
python -m venv venv
# Windows:
venv\Scripts\activate

# Only install what's actually needed
pip install requests pyinstaller

Step 2: Basic Packaging

To check if the script has any errors, run the default command:

pyinstaller my_tool.py

Now, you’ll see a dist/my_tool/ directory. Inside, there’s an exe file sitting among a bunch of .dll files. This is One-directory mode—it runs fast but is a bit messy to share.

Step 3: Bundle everything into a single file

To be more professional, use the --onefile parameter:

pyinstaller --onefile my_tool.py

Now in dist/, there’s only one single my_tool.exe file. Clean and simple!

Step 4: Add an Icon and hide the black screen

If your tool has a GUI (like Tkinter), you won’t want that black CMD window popping up. Add --noconsole and --icon for better aesthetics.

pyinstaller --onefile --noconsole --icon=logo.ico my_tool.py

Tips for scripts with attachments (Images, Configs)

This is the tricky part. When running --onefile, the file paths change. You need a function to find the correct file location in the system’s temporary directory:

import sys, os

def get_path(relative_path):
    # PyInstaller stores the temporary path in the _MEIPASS attribute
    base_path = getattr(sys, '_MEIPASS', os.path.abspath("."))
    return os.path.join(base_path, relative_path)

# Usage example
config_path = get_path("config.yaml")

When building, remember to declare the extra files using --add-data:

# Windows uses ; - Linux uses :
pyinstaller --onefile --add-data "config.yaml;." my_tool.py

Hard-won experience from the field

I’ve packaged dozens of automation tools for clients and gathered these important notes:

  1. Build where you run: You cannot build on Windows and expect it to run on Mac. If you want cross-platform support, you must have the corresponding machine (or virtual machine).
  2. Prioritize small libraries: If you only need to send mail, use the built-in smtplib instead of installing heavy third-party libraries.
  3. Solving Antivirus issues: If a client reports they can’t open the file, try using a Digital Signature or simply guide them to add the file to their antivirus software’s exclusion list.

I hope this article helps you overcome the fear of someone asking: “How do I run this .py file?”. Good luck!

Share:
Tags: