Hey folks! In this tutorial, we will learn the purpose and the basics of Python’s PyInstaller. So, let’s get started!
What is PyInstaller?
PyInstaller is a package in Python which bundles all the dependencies of Python applications in a single package.
We don’t need to install different packages or modules for different applications.
PyInstaller reads and analyzes our code and then discovers the modules that our program requires in order to execute. It then packages them into a single folder or a single executable file.
It is used of create .exe files for windows, .app files for Mac and distributable packages for Linux.
How to install PyInstaller?
We can download PyInstaller from PyPI. We can install it using pip package manager.
It is recommended to create a virtual environment and install PyInstaller there.
Enter the following command in windows command prompt-
pip install pyinstaller
Now, set the current directory to the location of your program program.py .
cd CurrentDirectory
Run the code given below. Here,program.py is the name of our given python script.
pyinstaller program.py
PyInstaller analyzes our code and does the following-
- Creates a program.spec file which contains the information about the files that should be packed up.
- A build folder is created which contains some log files and working files.
- A folder named dist will also be created which contains a .exe file with the same name as the given python script name.
Now there are 3 important elements of using the PyInstaller:
- The .spec file
- The build folder
- The dist folder
What is a spec file?
A Spec file, short for specification file is the first file that is built after the execution of pyinstaller program.py . It is stored in --specpath= directory. The spec file is an executable python code that tells PyIstaller how to process our Python script.
Modification of the spec file is not needed except in few cases where it is useful, when we want to:
- To bundle our data files with the app.
- To include run-time libraries that are unknown to PyInstaller.
- To add Python run-time options to the executable.
- To create a multiprogram bundle with merged common modules.
To create a spec file, run this command-
pyi-makespec program.py
This command creates program.py spec file. To build the application, we pass the spec file to pyinstaller command:
pyinstaller program.spec
What is build folder?
The build folder stores metadata and is useful for debugging.
build/program/warn-program.txt file in the build/ folder contains a lot of outputs to understand things better.
To review the output, rebuild the executable with --log-level=DEBUG option. It is recommended to save this output in order to refer to later. We can do this by-
pyinstaller --log-level=DEBUG program.py
This will create a build.txt file in the build folder which will contain many DEBUG messages.
What is the dist folder?
The dist folder contains the requirements and executables for the application. It contains a .exe file with the same name as our script.
The executable to run is dist/program/program.exe on windows.
What is ImportError ?
If PyInstaller is unable to detect all the dependencies properly, an ImportError error is seen. This happens when we use __import__( ). imports inside functions or hidden imports.
To resolve this we use, --hidden-import. This command includes packages and modules automatically.
Another way is using hook files that contain additional information that helps PyInstaller package up a dependency.
pyinstaller --additional-hooks-dir=. program.py
How to change name of our executable using PyInstaller?
To avoid our spec, build and executable file being named same as our python script name, we can use –name command.
pyinstaller program.py --name pythonproject
How to create a single executable file?
PyInstaller can also create a one-file app for our Python script. It contains an archive of all Python modules required by our python program.
To create only one executable file of your python script, run the code given below-
pyinstaller --onefile --windowed program.py
Testing our executable
We should always test our executable in a new machine without any development environment like virtualev, conda etc. as the main aim of PyInstaller executable is that user should not require any thing installed on their system.
Now, after the running the executable file, the following error occurs.
FileNotFoundError: 'version.txt' resource not found in 'importlib_resources'
This is because ‘importlib_resources’ requires version.txt file. We can add this file by the command given below.
pyinstaller program.py \
--add-data venv/reader/lib/python3.6/site-packages/importlib_resources/version.txt:importlib_resources
This will include version.txt file in new folder in importlib_resources folder.
Conclusion
In this article, we learned how to install PyInstaller, run, debug and test our executable. Stay tuned!