Troubleshooting PyInstaller
Roadblocks I encountered using PyInstaller with Windows and MacOS.
As an extension of a casual request from work, I wrote a Python script. Because this script was to be used in tandum with what we’re doing at work, I wrote the script on the work computer, which was a Windows 10 PC, and my IDE of choice was Notepad++ (I’m really starting to dig it).
The script was working great, and I wanted to distribute it to my co-workers. However, I didn’t know if every single one of my co-workers has a Python environment on their work computer. Plus, it would be quite annoying if they have to open up a cmd, navigate to the script’s folder, and type in “python lexis.py” everytime they want to use the script.
So I had to look for another solution, and I came across PyInstaller. At first glance, it was too elegant–and thus too good to be true. You just needed two commands, and you’ll be met with a shiny new executable ready to be distributed.
The two commands, as listed on the Quickstart, are as follow:
- To install
pip install -U pyinstaller
- To convert .py to .exe
pyinstaller your_program.py
- The command I use the most for my projects
# Windows
pyinstaller --onefile --windowed --icon="icon.ico" your_program.py
# MacOS
pyinstaller --onefile --windowed --icon="icon.icns" your_program.py
Roadblock #1
C:\Users\username>pyinstaller
'pyinstaller' is not recognized as an internal or external command,
operable program or batch file.
The immediate place I looked for solutions was this StackOverflow post.
By reading this thread, I realized that my Python environment was not set up correctly. I did not set my PATH environment variable to include the scripts.
So I followed this guide to change my PATH environment variables.
But it still wasn’t working. I thought the path to pyinstaller.exe that I had was incorrect, but I followed this answer and even found pyinstaller.exe in the path I was writing down, yet it still wasn’t working.
At this point I was kind of banging my head against the wall and went to video chat with my mom.
Roadblock #2
After I cleared my head a little, I decided to try PyInstaller on my MacBook.
Lo and behold, PyInstaller worked amazingly on MacOS.
One caveat though–if you’re packaging a distributable on MacOS, you’ll only get a UNIX executable file and an app.
But all of our work computers are running on Windows, this would not work at all if I wanted to distribute the executable to my coworkers.
PyInstaller still wasn’t working on my work Windows PC. I was already stuck on this for 2 hours, so I was on the verge of switching to Py2Exe.
But then I came across this StackOverflow post. And I remembered that before I started writing the script and was setting up the Python environment on the Windows PC, when I put “python” in the command line, I was directed to the Microsoft store. And this post’s answers made a lot more sense.
Though this still didn’t solve my problem. I tried moving the path where the pyinstaller.exe resides up in the PATH hierarchy, but that did nothing.
Roadblock #3
And another problem arose: now I can’t even run python anymore.
I knew somewhere along my debugging shenanigans I messed something up. After another 20 minutes of trying to recover the environment, I decided that it was easier to just reinstall Python altogether.
Only this time, I installed Python directly from the official website instead of the Microsoft store, and I MADE SURE to check the checkbox in the first panel of the installer where it adds itself as a PATH environment variable.
After this installation was done, I reinstalled pyinstaller, and I was able to get my one-file bundled Windows executable.
Roadblock #4
After this initial MVP is finished, I got to work on another personal project with Python for my parents. This time the project was for MacOS.
I wrote the initial script with my mom’s MacBook Air M2, but when I tried to use PyInstaller there, an error popped up saying her computer hasn’t agreed to xcode stuff, and downloading that stuff would take a bit of time.
So I sent the script from my mom’s laptop to my own daily driver MacBook Pro. Then, when I tried to use PyInstaller there, I got an error saying something to the effect of “No module named ’tkinter’ found” which perplexed me for a good amount of time.
What finally solved this issue was actually absurdly simple: I moved the script to another folder and used PyInstaller to package it there. Not exactly sure why this fixed it, but I’ll take it.
Roadblock #5
My parents wanted to use this app on their old MacBook as well, and not just their new one (which was working fine). I thought I could just send the .app to their old MacBook, but the old MacBook could not open the app, saying that the app is not supported on this machine.
I suspect that this may be because of the fact that I packaged this app on a MacBook with Apple Silicon, and their new MacBook also has Apple Silicon, but their old MacBook is still running on Intel chip.
Conclusion
TLDR:
- For Windows, reinstall python, remember to check the “Add to PATH” checkbox when installing python. Check that the “App execution aliases” under your Windows settings for python.exe and python3.exe are turned off. Then try reinstalling pyinstaller.
- For MacOS, if the distributable is created on Apple Silicon, it may not work with Intel chip, so it would need to be repackaged there.
This is mainly for future me, in case I come across similar problems again.