PyInstaller: Converting Python Scripts into Standalone Executables Read it later

If you’re a Python developer, chances are you’ve asked yourself this question: “How can I convert my Python script into an executable file?” It’s a common dilemma when you want to share your amazing Python application with the world. Well, worry no more! In this blog, we’re going to dive into converting your Python program into a standalone executable using a fantastic Python module called PyInstaller.

The Application Distribution Problem

Imagine you’re someone who wants to use a Python application, but you’re not a developer. You’re excited about the possibilities, but when you start the setup process, you hit a roadblock.

It begins with the opening of a Terminal, which might seem intimidating and unfamiliar. This obstacle alone can discourage many potential users from even attempting to install the application. And if they do decide to proceed, they’re confronted with complex instructions involving virtual environments, specific Python versions, and a long list of potential dependencies.

The Real Problem

Put yourself in the shoes of a non-developer who wants to set up a new machine for Python development. The steps involved might seem daunting and confusing:

1. First, you need to download and install a specific version of Python. But why do you need a particular version? It’s not immediately clear.
2. Then, you have to set up pip, which is the package installer for Python. But again, what is pip, and why is it necessary?
3. Next, you’re instructed to set up a virtual environment. But what exactly is a virtual environment, and why do you need one? It’s unfamiliar territory for non-developers.
4. Once you’ve sorted out the virtual environment, you need to get a copy of the code for the application you want to use. But how do you access the code? Where do you find it?
5. Last but not least, you have to install the dependencies required by the application. But what are dependencies, and why are they crucial for the application to work? It’s a concept that may seem perplexing to someone unfamiliar with programming.

When you step back and reflect on this setup process, it becomes evident that these steps don’t make much sense to non-developers. It’s understandable that they might feel overwhelmed and discouraged from proceeding any further.

The Saviour

This distribution problem highlights the need for a user-friendly solution that simplifies the process of sharing and installing Python applications. That’s where PyInstaller comes into play. It offers a seamless way to package Python code into standalone executables, eliminating the complexities of installation and dependencies. With PyInstaller, users can effortlessly run Python applications without worrying about technical setup or unfamiliar terminology.

By addressing the distribution problem, PyInstaller opens doors to a wider audience, enabling non-developers to explore and benefit from the world of Python applications. Its ease of use and straightforward approach make it a valuable tool for sharing Python projects with simplicity and efficiency.

What is Pyinstaller?

PyInstaller is a tool that packages Python code into standalone executables. It analyzes your code and dependencies, creating a single file that can be run without Python or additional installations. It simplifies sharing and allows cross-platform compatibility. With PyInstaller, distributing Python programs is effortless!

Installing PyInstaller

Now that you’re ready to embark on your journey with PyInstaller, let’s dive into the installation process. Don’t worry, it’s a breeze! Just follow these simple steps, and you’ll have PyInstaller up and running on your system in no time.

Step 1: Open up your trusted terminal or command prompt. It’s your gateway to the magical world of PyInstaller.

Step 2: If you’re a fan of creating organized projects (who isn’t?), creating a virtual environment is a great way to keep things neat and tidy. While it’s optional, we highly recommend it. To create a virtual environment, type in the following command:

python3 -m venv myenv

By doing this, you’ll have a cozy little space specifically designated for PyInstaller.

Step 3: It’s time to activate your virtual environment. The command may vary slightly depending on your operating system, so choose the one that matches your setup:

• If you’re a Windows user, type:

myenv\Scripts\activate

• For macOS and Linux enthusiasts, enter:

source myenv/bin/activate

With the virtual environment activated, you’re in the PyInstaller zone!

Step 4: Now comes the exciting part – installing PyInstaller itself. It’s just a single command away. Type the following in your terminal or command prompt:

pip install pyinstaller

Now that PyInstaller is installed and ready to go, let’s move on to the exciting part – packaging your Python code into standalone executables.

How to use PyInstaller?

To use PyInstaller effectively, it’s essential to understand its syntax and the various components involved. Let’s dive into the syntax and explore each component in detail.

PyInstaller Syntax:

pyinstaller [options] script [script …] | specfile

Now, let’s break down the components of the above command:

1. pyinstaller: This is the command that invokes PyInstaller and tells it to package your Python code into a standalone executable.
2. options: These are optional flags that modify the behavior of PyInstaller. You can include various options to customize the packaging process according to your needs. We’ll explore some of these options later in this guide.
3. script [script …]: This refers to the Python script or scripts you want to package. You can specify a single script or multiple scripts separated by spaces.
4. | specfile: The | symbol represents a choice between specifying scripts directly or using a specfile. A specfile is a Python script that provides detailed instructions for PyInstaller on how to package your code. In most cases, specifying scripts directly using the command line is sufficient.

Also read, how you can enable text-to-speech capability in your project by incorporating pyttsx3.

Packaging Your Python Code

To get started, open your terminal and navigate to the directory where your Python script (ending with the .py extension) is located. Then, execute the following command:

$ pyinstaller yourprogram.py

Now, let’s understand what happens when you run the above command:

• PyInstaller creates a file named yourprogram.spec in the same directory as your script. This spec file contains configuration details and options for PyInstaller.
• A folder named build is created in the same directory as the script if it doesn’t already exist. This folder is used to store log files and working files during the packaging process.
• PyInstaller generates log files and working files within the build folder.
• If a folder named dist doesn’t exist in the same directory as the script, PyInstaller creates one. The dist folder is where the bundled application and the executable (.exe) file are located.
• The dist folder contains the bundled app, which includes the necessary files and dependencies to run the application independently.

When you run the .exe file generated by PyInstaller, you’ll obtain the same output as when running your script through the Python interpreter.

However, a challenge remains: you cannot simply share the .exe file alone, as it requires multiple dependency files to run correctly.

Fortunately, PyInstaller provides various flags that enable us to modify and customize our bundled application. These flags allow us to include additional files, control the behavior of the bundled app, and make it more self-contained.

PyInstaller Packaging Options

When using PyInstaller, you have the flexibility to choose how you want your Python code to be packaged. PyInstaller offers two main options for generating the bundled executable: creating a one-folder bundle or a one-file bundled executable. Let’s explore these options in more detail.

One-Folder Bundle (–onedir)

The --onedir option allows you to create a one-folder bundle that contains an executable. This means that all the necessary files, including the bundled executable and any required dependencies, will be stored within a single folder. This option is the default setting when using PyInstaller.

To generate a one-folder bundle, simply run PyInstaller with the --onedir option followed by the name of your script. Here’s an example:

$ pyinstaller --onedir my_script.py

PyInstaller will analyze your code, detect dependencies, and generate a folder containing the bundled executable along with any additional files needed to run your application.

One-File Bundled Executable (–onefile)

The --onefile option allows you to create a single executable file that encapsulates your Python code and all its dependencies. This means that everything required to run your application is contained within a single file, making it more convenient for distribution and sharing.

To generate a one-file bundled executable, use the “–onefile” option instead of “–onedir” when running PyInstaller. Here’s an example:

$ pyinstaller --onefile my_script.py

PyInstaller will package your code into a single executable file, making it easier to distribute and run on different systems.

Specifying the Spec File Location (–specpath DIR)

The --specpath option allows you to specify the folder where the generated spec file should be stored. The spec file contains information about your bundled application, including the configuration and dependencies. By default, PyInstaller will save the spec file in the current directory.

To specify a custom directory for the spec file, use the --specpath option followed by the desired directory path. Here’s an example:

$ pyinstaller --specpath /path/to/spec my_script.py

This will generate the spec file in the specified directory, providing you with more control over the packaging process.

Naming the Bundle and Spec File (–name)

The --name option allows you to assign a specific name to both the bundled application and the spec file. By default, PyInstaller uses the basename of the first script as the name for both.

To assign a custom name, use the --name option followed by the desired name. Here’s an example:

$ pyinstaller --name myapp my_script.py

This command will generate a bundled application and spec file with the name myapp.

Customizing the Bundling Option

When it comes to packaging your Python code with PyInstaller, you have the flexibility to customize the process according to your specific needs. This section will guide you through some handy customization options that PyInstaller offers, allowing you to tailor the packaging experience to suit your requirements.

PyInstaller –hidden-import: Resolve Missing Dependencies

PyInstaller’s --hidden-import option comes to the rescue when the tool fails to automatically detect certain dependencies in your Python code. It allows you to specify the names of packages or modules that you want to include in your executable.

Imagine you have a project where the requests library is imported inside a function. Normally, PyInstaller wouldn’t recognize this import and might exclude the requests package from the bundled executable. However, with the --hidden-import option, you can ensure that requests is included.

To use --hidden-import, simply append it to your PyInstaller build command, followed by the name of the package or module you want to include. In our example, we would add --hidden-import=requests to the command.

Here’s an example of how the command might look:

$ pyinstaller cli.py --hidden-import=requests

If your code has multiple hidden imports, you can specify them all by including --hidden-import multiple times in the same command. This ensures that all necessary packages and modules are included in your final executable.

PyInstaller –add-data: Add Dependency Files

When packaging your Python code with PyInstaller, you may often come across situations where your application requires additional files, such as data files or configuration files, to function properly.

The --add-data option enables you to specify the path to the additional file(s) you want to include and where they should be located within the bundled executable. This ensures that your application has access to these files when it is running independently.

To use the --add-data option, follow this syntax:

$ pyinstaller --add-data "<path_to_file>:<destination_path>" my_script.py

Let’s break down the command:

• <path_to_file> represents the path to the file you want to include. This could be a data file, a configuration file, or any other necessary file.
• <destination_path> specifies the directory or location within the bundled executable where you want to place the file. You can use a dot (.) to indicate the current directory.

For example, suppose you have a data file named data.txt located in the same directory as your script. To include this file in the bundled executable and place it in the same directory as the script when running, you would use the following command:

$ pyinstaller --add-data "data.txt:." my_script.py

By using the --add-data option, you can ensure that your application has access to all the required files it needs, making it self-contained and ready for distribution.

PyInstaller –distpath: Set Output Directory

When you package your Python code with PyInstaller, it generates a bundled executable by default in a directory called dist. However, there might be instances when you prefer to have more control over where the output files are saved. PyInstaller offers a handy option called --distpath that allows you to specify a custom output directory.

The —distpath option lets you set the destination directory for the packaged executable and related files. This means you can choose any location on your computer where you want the output files to be stored. By specifying a custom output directory, you have the flexibility to organize your packaged code according to your preferences.

To use the --distpath option, use the following syntax:

$ pyinstaller --distpath /path/to/output my_script.py

Here, /path/to/output represents the location where you want to store the packaged files. Make sure to replace it with the actual directory path on your system.

Windows & Mac OS X Options

When using PyInstaller, you have specific options available for Windows and Mac OS X platforms. These options allow you to customize the behavior of the bundled executable and provide a more seamless user experience.

Opening a Console Window (Windows)

Option: -c, --console, --nowindowed

This option opens a console window for standard input and output. By default, PyInstaller displays a console window on Windows unless the first script being packaged has a .pyw extension (which indicates a Windows GUI application).

Example:

pyinstaller -c my_script.py

Windowed Mode (Windows and Mac OS X)

Option: -w, --windowed, --noconsole

This option prevents the console window from being displayed during the execution of the bundled executable. It is particularly useful when creating graphical applications or applications intended for end-users who don’t require access to the console interface. On Mac OS X, using this option also triggers the creation of a Mac OS .app bundle.

Example:

pyinstaller -w my_script.py

Applying an Icon (Windows and Mac OS X)

Option: -i | --icon <FILE.ico or FILE.exe,ID or FILE.icns or Image or "NONE">

This option allows you to specify an icon file to be associated with the bundled executable. You can use different formats for different platforms: .ico for Windows and .icns for Mac OS X.

PyInstaller also supports using an image file, which it can translate into the correct format using the Pillow library. Specifying "NONE" as the icon file results in the operating system displaying a default icon.

Example:

pyinstaller -i my_icon.ico my_script.py

Wrapping Up

In conclusion, PyInstaller is a powerful tool that simplifies the process of packaging Python code into standalone executables. With PyInstaller, you can easily distribute your applications to others without worrying about dependencies or installation procedures. By following the steps outlined in this guide, you can leverage PyInstaller’s features to customize the packaging process according to your needs.

Explore the official documentation and embark on your journey of sharing your Python projects with the world. Happy coding with PyInstaller!

Frequently Asked Questions (FAQs)

Reference

1. PyInstaller documentation
2. PyInstaller GitHub Repository