Guide to Packaging Python Code into EXE: Avoiding Pitfalls with PyInstaller

Click the blue text to follow us

Hello everyone, I am Cai Ge! Today we will talk about how to package Python code into an EXE file, especially using the pyinstaller tool. Many people may want to package their projects into executable files after learning Python, making it easier to share and use. However, there are often some pitfalls during the packaging process, and today I will summarize these experiences to help you successfully complete the packaging!

1. What is PyInstaller?

pyinstaller is a tool that packages Python programs into standalone executable files, supporting multiple platforms such as Windows, Linux, and macOS. With it, we can bundle Python scripts and their dependent libraries into a single EXE file, allowing others to run our programs without needing to install a Python environment.

Tip

Before packaging, please ensure that your code runs correctly on your local machine.

2. Installing PyInstaller

Before using pyinstaller, you need to install it first. You can easily install it using the pip command:

pip install pyinstaller

Notes

Make sure your pip is up to date; you can upgrade it using pip install --upgrade pip.

3. Packaging Your First Python File

Assuming we have a simple Python script hello.py with the following content:

print("Hello, World!")

Using pyinstaller to package this script is very simple. Open the command line and enter the following command:

pyinstaller --onefile hello.py

Code Explanation

--onefile option indicates that all files will be packaged into a single EXE file.
After execution, an hello.exe will be generated in the dist folder, which you can run directly.

4. Handling Dependency Files

If your program depends on external files, such as configuration files or images, you need to ensure these files are included during packaging. If you accidentally miss them, the program may encounter errors at runtime.

Handling Method

When packaging, you can use the --add-data option to include additional files. For example:

pyinstaller --onefile --add-data "config.json;." hello.py

Tip

On Windows, use a semicolon ; to separate the source path and target path; on Linux, use a colon :.

5. Debugging Packaged Programs

If there are issues with the packaged program, you can debug by checking the logs in the generated build folder.

Tip

Using the --debug option can help you better debug the program:

pyinstaller --onefile --debug hello.py

6. Common Errors and Solutions

Error 1: Missing Modules

Sometimes, when running the EXE file after packaging, it may prompt that certain modules are missing. This is usually because pyinstaller did not automatically detect the dependencies.

Solution: Use the --hidden-import option to manually add the missing modules.

Error 2: Icon Issues

If you want to add an icon to the packaged EXE file, you can use the --icon option:

pyinstaller --onefile --icon=myicon.ico hello.py

Tip

Ensure the path to the icon file is correct to avoid file not found errors.

7. Packaging Complex Projects

For more complex projects, there may be multiple Python files and dependencies. You can create a spec file to configure packaging options more flexibly. First, run:

pyinstaller hello.py

This will generate a hello.spec file, which you can modify as needed, and then use:

pyinstaller hello.spec

to perform the packaging.

Conclusion

Today we learned how to use pyinstaller to package Python code into an EXE file, as well as some common issues and solutions encountered during the packaging process. I hope these tips can help you successfully complete the packaging and share your work!

Take a break, and we will continue tomorrow!

Today’s learning is over, take a break!