PyInstaller

https://pyinstaller.org/en/stable/
Admin
PyInstaller bundles a Python application and all its dependencies into a single package, allowing...
Tokens:285,778
Snippets:2,091
Trust Score:9.3
Update:4 days ago
Show doc for...
Tokens:
Raw
### Setup virtual environment and dependencies

Source: https://pyinstaller.org/en/stable/_sources/development/testing.rst.txt

Create a virtual environment and install the necessary testing tools.

```bash
pip install --user virtualenv
virtualenv /tmp/venv
. /tmp/venv/bin/activate
pip install -r tests/requirements-tools.txt
```

--------------------------------

### Example Vagrant usage to build bootloader

Source: https://pyinstaller.org/en/stable/bootloader-building.html

Example commands to start a Linux64 VM (which builds the bootloader), halt it, and verify the bootloader has been rebuilt using git status.

```bash
vagrant up linux64      # will also build the bootloader
vagrant halt linux64    # or `destroy`

# verify the bootloader has been rebuild
git status ../PyInstaller/bootloader/

```

--------------------------------

### Manage Vagrant build guests

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Example commands to start, stop, and verify the bootloader build status within a Vagrant guest.

```bash
vagrant up linux64      # will also build the bootloader
  vagrant halt linux64    # or `destroy`

  # verify the bootloader has been rebuild
  git status ../PyInstaller/bootloader/
```

--------------------------------

### Install PyInstaller from manual git checkout

Source: https://pyinstaller.org/en/stable/_sources/installation.rst.txt

Clone the repository and install the package from the local directory.

```bash
git clone https://github.com/pyinstaller/pyinstaller
cd pyinstaller
pip install .
```

--------------------------------

### POSIX resource tracker spawn command

Source: https://pyinstaller.org/en/stable/_sources/common-issues-and-pitfalls.rst.txt

Example of the command-line arguments used to start the resource tracker process on POSIX systems using the spawn method.

```bash
python -c from multiprocessing.resource_tracker import main;main(5)
```

--------------------------------

### Install testing tools

Source: https://pyinstaller.org/en/stable/_sources/development/quickstart.rst.txt

Install the necessary tools required for running tests locally.

```bash
pip install -r tests/requirements-tools.txt
```

--------------------------------

### Install PyInstaller from source

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Install the package after rebuilding the bootloader. Use the editable flag for development purposes.

```bash
cd ..
pip install .
pip install -e .
```

--------------------------------

### Using check_requirement

Source: https://pyinstaller.org/en/stable/hooks.html

Examples of checking PEP 0508 requirements for installed packages.

```python
# Assume Pillow 10.0.0 is installed.
>>> from PyInstaller.utils.hooks import check_requirement
>>> check_requirement('Pillow')
True
>>> check_requirement('Pillow < 9.0')
False
>>> check_requirement('Pillow >= 9.0, < 11.0')
True
```

--------------------------------

### Install Build Dependencies on Fedora/RedHat

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Install the necessary development tools for building the bootloader on Fedora, RedHat, and derivatives.

```shell
sudo yum groupinstall "Development Tools"
sudo yum install zlib-devel
```

--------------------------------

### Install PyInstaller from git

Source: https://pyinstaller.org/en/stable/_sources/installation.rst.txt

Install PyInstaller directly using pip's built-in git support.

```bash
pip install git+https://github.com/pyinstaller/pyinstaller
```

--------------------------------

### Install Build Dependencies on Debian/Ubuntu

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Install the necessary development tools for building the bootloader on Debian or Ubuntu-like systems.

```shell
sudo apt-get install build-essential zlib1g-dev
```

--------------------------------

### Build documentation locally

Source: https://pyinstaller.org/en/stable/_sources/development/documentation.rst.txt

Commands to install documentation dependencies, build the HTML documentation, and open the result in a browser.

```bash
pip install -r doc/requirements.txt
cd doc
make html
xdg-open _build/html/index.html
```

--------------------------------

### Install flake8 and yapf

Source: https://pyinstaller.org/en/stable/_sources/development/coding-conventions.rst.txt

Install the required formatting and linting tools using pip.

```bash
pip install flake8 yapf==0.43.0 toml
```

--------------------------------

### POSIX worker process spawn command

Source: https://pyinstaller.org/en/stable/_sources/common-issues-and-pitfalls.rst.txt

Example of the command-line arguments used to start a worker process on POSIX systems using the spawn method.

```bash
python -c "from multiprocessing.spawn import spawn_main; spawn_main(tracker_fd=6, pipe_handle=8)" --multiprocessing-fork
```

--------------------------------

### Install PyInstaller development version

Source: https://pyinstaller.org/en/stable/_sources/installation.rst.txt

Install the current development version directly from the GitHub tarball.

```bash
pip install https://github.com/pyinstaller/pyinstaller/tarball/develop
```

--------------------------------

### Graceful console application shutdown with SetConsoleCtrlHandler

Source: https://pyinstaller.org/en/stable/_sources/feature-notes.rst.txt

This example demonstrates how to install a console handler to catch signals and perform a graceful shutdown by saving the application state to a file. It requires the pywin32 library.

```python
# console_counter.py
import sys
import time
import pathlib

import win32api  # pip install pywin32


def console_handler(signal):
    print(f"Console handler (signal {signal})!")
    global keep_running
    keep_running = False
    # Sleep until process either finishes or is killed by the OS
    time.sleep(20)
    return True


if __name__ == '__main__':
    keep_running = True

    # Install console handler
    win32api.SetConsoleCtrlHandler(console_handler, 1)

    # Restore state, if available
    state_file = pathlib.Path.home() / 'counter_state.txt'
    if state_file.is_file():
        print(f"Restoring state from {state_file}...", file=sys.stderr)
        try:
            with open(state_file, 'r') as fp:
                counter = int(fp.readline())
        except Exception:
            print("Failed to restore state from file!", file=sys.stderr)
            counter = 0
    else:
        print("State file does not exist!", file=sys.stderr)
        counter = 0

    print(f"Initial counter value: {counter}", file=sys.stderr)

    # Main loop
    while keep_running:
        print(f"Counter value: {counter}")
        counter += 1
        time.sleep(1)

    # Clean-up
    print(f"Storing state to {state_file}...", file=sys.stderr)
    try:
        with open(state_file, 'w') as fp:
            print(f"{counter}", file=fp)
    except Exception:
        print(f"Failed to store state to {state_file}!", file=sys.stderr)
```

--------------------------------

### Running PyInstaller with paths

Source: https://pyinstaller.org/en/stable/_sources/usage.rst.txt

Examples of providing paths to scripts or spec files on different operating systems.

```shell
pyinstaller ~/myproject/source/myscript.py
```

```shell
pyinstaller "C:\Documents and Settings\project\myscript.spec"
```

--------------------------------

### Install Vagrant plugins for bootloader building

Source: https://pyinstaller.org/en/stable/bootloader-building.html

Install the required Vagrant plugins 'vagrant-reload' and 'vagrant-scp' for managing the virtual machines used to build bootloaders.

```bash
vagrant plugin install vagrant-reload vagrant-scp

```

--------------------------------

### Install Vagrant plugins

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Command to install the required vagrant-reload and vagrant-scp plugins for managing build guests.

```bash
vagrant plugin install vagrant-reload vagrant-scp
```

--------------------------------

### Configure Vagrant build with environment variables

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Examples of passing configuration parameters to the Vagrantfile using environment variables.

```bash
GUI=1 TARGET=OSX vagrant up linux64
```

```bash
export TARGET=OSX
    vagrant provision linux64
```

--------------------------------

### Example spec file for a minimal one-folder app

Source: https://pyinstaller.org/en/stable/_sources/spec-files.rst.txt

A shortened example of a spec file for a minimal one-folder app. It creates instances of Analysis, PYZ, EXE, and COLLECT classes. The Analysis instance takes a list of script names and analyzes imports and dependencies.

```python
a = Analysis(['minimal.py'],
         pathex=['/Developer/PItests/minimal'],
         binaries=None,
         datas=None,
         hiddenimports=[],
         hookspath=None,
         runtime_hooks=None,
         excludes=None)
pyz = PYZ(a.pure)
exe = EXE(pyz,... )
coll = COLLECT(...)
```

--------------------------------

### Build a 32-bit bootloader on a 64-bit machine

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Use the --target-arch option to specify the architecture, provided the necessary compiler and development files are installed.

```bash
python ./waf all --target-arch=32bit
```

--------------------------------

### Prepare environment for forced bootloader rebuild

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Clean existing installations and cache to ensure a fresh build from source during the next pip install.

```bash
pip uninstall PyInstaller
pip cache remove PyInstaller
```

--------------------------------

### Install PyInstaller via pip

Source: https://pyinstaller.org/en/stable/_sources/index.rst.txt

Use this command to install the latest version of PyInstaller from PyPI.

```bash
pip install -U pyinstaller
```

--------------------------------

### Implement Qt-based open event handling

Source: https://pyinstaller.org/en/stable/_sources/feature-notes.rst.txt

Example of a Qt application and its corresponding spec file. The application uses a custom QApplication to filter QFileOpenEvent and emit a signal for handling.

```python
# eventlogger_qt.py
import sys
import signal

from PySide2 import QtCore, QtWidgets


class Application(QtWidgets.QApplication):
    """
    QtWidgets.QApplication with extra handling for macOS Open
    document/URL events.
    """
    openFileRequest = QtCore.Signal(QtCore.QUrl, name='openFileRequest')

    def event(self, event):
        if event.type() == QtCore.QEvent.FileOpen:
            # Emit signal so that main window can handle the given URL.
            # Or open a new application window for the file, or whatever
            # is appropriate action for your application.
            self.openFileRequest.emit(event.url())
            return True
        return super().event(event)


class MainWindow(QtWidgets.QMainWindow):
    """
    Main window.
    """
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.resize(800, 600)

        self.setWindowTitle("Qt-based event logger")

        # Construct the UI
        self.scroll_area = QtWidgets.QScrollArea()
        self.scroll_area.setWidgetResizable(True)
        self.setCentralWidget(self.scroll_area)

        self.text_edit = QtWidgets.QTextEdit()
        self.scroll_area.setWidget(self.text_edit)
        self.text_edit.setReadOnly(True)

    def append_message(self, msg):
        """
        Append message to text view.
        """
        self.text_edit.append(msg)

    def handle_open_file_request(self, url):
        self.append_message(f"Open request: {url.toString()}")


if __name__ == '__main__':
    # Make Ctrl+C work
    signal.signal(signal.SIGINT, signal.SIG_DFL)

    app = Application(list(sys.argv))

    window = MainWindow()
    window.show()

    window.append_message("Application started!")
    window.append_message(f"Args: {sys.argv[1:]}")

    app.openFileRequest.connect(window.handle_open_file_request)

    app.exec_()
```

```python
# eventlogger_qt.spec
a = Analysis(['eventlogger_qt.py'])

pyz = PYZ(a.pure)

exe = EXE(
    pyz,
    a.scripts,
    exclude_binaries=True,
    name='eventlogger_qt',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=False,
    console=False,
    argv_emulation=False,  # unnecessary as app handles events
)

coll = COLLECT(
    exe,
    a.binaries,
    a.datas,
    strip=False,
    upx=False,
    name='eventlogger_qt'
)
```

--------------------------------

### Run full test suite with library coverage

Source: https://pyinstaller.org/en/stable/_sources/development/testing.rst.txt

Install additional test packages and run the full test suite for better coverage.

```bash
pip install -U -r tests/requirements-libraries.txt
pytest tests/unit tests/functional
```

--------------------------------

### Combine markup and links

Source: https://pyinstaller.org/en/stable/_sources/development/documentation.rst.txt

Example of using a replacement directive to create a link for the pip command.

```rst
The easiest way to install PyInstaller is using |pip|_::

.. |pip| replace:: :command:`pip`
.. _pip: https://pip.pypa.io/
```

--------------------------------

### Include specific GStreamer plugins

Source: https://pyinstaller.org/en/stable/_sources/hooks-config.rst.txt

Example of optimizing application size by explicitly including only the required GStreamer plugins for audio playback.

```python
# The not-completely-optimized list of gstreamer plugins for playing a FLAC
# (and possibly some other) audio files on linux and Windows.
gst_include_plugins = [
    # gstreamer
    "coreelements",
    # gstreamer-plugins-base
    "alsa",  # Linux audio output
    "audioconvert",
    "audiomixer",
    "audiorate",
    "audioresample",
    "ogg",
    "playback",
    "rawparse",
    "typefindfunctions",
    "volume",
    "vorbis",
    # gstreamer-plugins-good
    "audioparsers",
    "auparse",
    "autodetect",
    "directsound", # Windows audio output
    "flac",
    "id3demux",
    "lame",
    "mpg123",
    "osxaudio",  # macOS audio output
    "pulseaudio",  # Linux audio output
    "replaygain",
    "speex",
    "taglib",
    "wavparse",
    # gstreamer-plugins-bad
    "wasapi",  # Windows audio output
]

a = Analysis(
    ["audio_player.py"],
    ...,
    hooksconfig={
        "gstreamer": {
            "include_plugins": gst_include_plugins,
        },
    },
    ...,
)
```

--------------------------------

### Install PyInstaller in editable mode

Source: https://pyinstaller.org/en/stable/_sources/installation.rst.txt

Install the package in editable mode so that changes to the source code take effect immediately without re-installation.

```bash
pip install -e .
```

--------------------------------

### Define Version and Product Version Tuples

Source: https://pyinstaller.org/en/stable/_sources/usage.rst.txt

Example of the four-element tuple format used for FileVersion and ProductVersion in a version text file.

```text
filevers=(2, 0, 4, 0),
prodvers=(2, 0, 4, 0),
```

--------------------------------

### Clone the fork

Source: https://pyinstaller.org/en/stable/_sources/development/pull-requests.rst.txt

Initial setup to clone your personal fork of the PyInstaller repository to your local machine.

```bash
git clone git@github.com:YOUR_GITHUB_USERNAME/pyinstaller.git
cd pyinstaller
```

--------------------------------

### Folder structure for module data

Source: https://pyinstaller.org/en/stable/spec-files.html

Example of a folder arrangement for a module containing data files.

```text
helpmod
    __init__.py
    helpmod.py
    help_data.txt
```

--------------------------------

### Example Operation not permitted error message

Source: https://pyinstaller.org/en/stable/_sources/when-things-go-wrong.rst.txt

An example of the error message encountered when shared libraries fail to map due to filesystem permissions.

```text
./hello: error while loading shared libraries: libz.so.1: 
failed to map segment from shared object: Operation not permitted
```

--------------------------------

### Install Python with shared libpython

Source: https://pyinstaller.org/en/stable/_sources/development/venv.rst.txt

Installs Python 3.5.0 with shared libraries, which is necessary for PyInstaller to work.

```bash
env PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install 3.5.0
```

--------------------------------

### Force bootloader rebuild during installation

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Set the required environment variables and use the --no-binary flag to trigger a rebuild during the pip installation process.

```bash
pip install --no-binary=pyinstaller .
```

--------------------------------

### Install build tools via Chocolatey

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Use this command in an administrative PowerShell to install Python and the Visual Studio 2019 C++ build tools.

```powershell
choco install -y python3 visualstudio2019-workload-vctools
```

--------------------------------

### Verify PyInstaller installation

Source: https://pyinstaller.org/en/stable/_sources/installation.rst.txt

Check that the pyinstaller command is available and display its version.

```bash
pyinstaller --version
```

--------------------------------

### Qt-based event logger application and .spec file

Source: https://pyinstaller.org/en/stable/feature-notes.html

This example demonstrates a Qt application that handles QFileOpenEvent and its associated PyInstaller .spec file configured for macOS bundle integration.

```python
# eventlogger_qt.py
import sys
import signal

from PySide2 import QtCore, QtWidgets


class Application(QtWidgets.QApplication):
    """
    QtWidgets.QApplication with extra handling for macOS Open
    document/URL events.
    """
    openFileRequest = QtCore.Signal(QtCore.QUrl, name='openFileRequest')

    def event(self, event):
        if event.type() == QtCore.QEvent.FileOpen:
            # Emit signal so that main window can handle the given URL.
            # Or open a new application window for the file, or whatever
            # is appropriate action for your application.
            self.openFileRequest.emit(event.url())
            return True
        return super().event(event)


class MainWindow(QtWidgets.QMainWindow):
    """
    Main window.
    """
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.resize(800, 600)

        self.setWindowTitle("Qt-based event logger")

        # Construct the UI
        self.scroll_area = QtWidgets.QScrollArea()
        self.scroll_area.setWidgetResizable(True)
        self.setCentralWidget(self.scroll_area)

        self.text_edit = QtWidgets.QTextEdit()
        self.scroll_area.setWidget(self.text_edit)
        self.text_edit.setReadOnly(True)

    def append_message(self, msg):
        """
        Append message to text view.
        """
        self.text_edit.append(msg)

    def handle_open_file_request(self, url):
        self.append_message(f"Open request: {url.toString()}")


if __name__ == '__main__':
    # Make Ctrl+C work
    signal.signal(signal.SIGINT, signal.SIG_DFL)

    app = Application(list(sys.argv))

    window = MainWindow()
    window.show()

    window.append_message("Application started!")
    window.append_message(f"Args: {sys.argv[1:]}")

    app.openFileRequest.connect(window.handle_open_file_request)

    app.exec_()
```

```python
# eventlogger_qt.spec
a = Analysis(['eventlogger_qt.py'])

pyz = PYZ(a.pure)

exe = EXE(
    pyz,
    a.scripts,
    exclude_binaries=True,
    name='eventlogger_qt',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=False,
    console=False,
    argv_emulation=False,  # unnecessary as app handles events
)

coll = COLLECT(
    exe,
    a.binaries,
    a.datas,
    strip=False,
    upx=False,
    name='eventlogger_qt'
)

app = BUNDLE(
    coll,
    name='eventlogger_qt.app',
    # Register custom protocol handler and custom file extension
    info_plist={
        'CFBundleURLTypes': [{
            'CFBundleURLName': 'MyCustomUrlSchemaQt',
            'CFBundleTypeRole': 'Viewer',
            'CFBundleURLSchemes': ['pyi-qt'],
        }],
        'CFBundleDocumentTypes': [{
            'CFBundleTypeName': 'MyCustomFileTypeQt',
            'CFBundleTypeExtensions': [
                'pyi_qt',
            ],
            'CFBundleTypeRole': "Viewer",
         }],
    }
)
```

--------------------------------

### Run PyInstaller in a synchronized environment

Source: https://pyinstaller.org/en/stable/_sources/usage.rst.txt

Example command sequence to build an application from a synchronized folder while keeping temporary and distribution files local to the virtual machine.

```bash
cd ~/NextCloud/project_folder/src # GNU/Linux, Mac -- Windows similar
rm *.pyc # get rid of modules compiled by another Python
pyinstaller --workpath=path-to-local-temp-folder  \
            --distpath=path-to-local-dist-folder  \
            ...other options as required...       \
            ./myscript.py
```

--------------------------------

### Add data files via CLI

Source: https://pyinstaller.org/en/stable/_sources/runtime-information.rst.txt

Example of using the --add-data option to include data files in a package structure.

```bash
PyInstaller --add-data="/path/to/my_library/file.dat:./my_library"
```

--------------------------------

### Install the latest PyInstaller development version via pip

Source: https://pyinstaller.org/en/stable/_sources/when-things-go-wrong.rst.txt

Use this command to install the latest development version of PyInstaller directly from the GitHub repository.

```bash
pip install https://github.com/pyinstaller/pyinstaller/archive/develop.zip
```

--------------------------------

### GStreamer plugin optimization configuration

Source: https://pyinstaller.org/en/stable/hooks-config.html

Example of limiting collected GStreamer plugins to reduce frozen application size.

```python
# The not-completely-optimized list of gstreamer plugins for playing a FLAC
# (and possibly some other) audio files on linux and Windows.
gst_include_plugins = [
    # gstreamer
    "coreelements",
    # gstreamer-plugins-base
    "alsa",  # Linux audio output
    "audioconvert",
    "audiomixer",
    "audiorate",
    "audioresample",
    "ogg",
    "playback",
    "rawparse",
    "typefindfunctions",
    "volume",
    "vorbis",
    # gstreamer-plugins-good
    "audioparsers",
    "auparse",
    "autodetect",
    "directsound", # Windows audio output
    "flac",
    "id3demux",
    "lame",
    "mpg123",
    "osxaudio",  # macOS audio output
    "pulseaudio",  # Linux audio output
    "replaygain",
    "speex",
    "taglib",
    "twolame",
    "wavparse",
    # gstreamer-plugins-bad
    "wasapi",  # Windows audio output
]

a = Analysis(
    ["audio_player.py"],
    ...,
    hooksconfig={
        "gstreamer": {
            "include_plugins": gst_include_plugins,
        },
    },
    ...,
)
```

--------------------------------

### Set Version Resource via CLI

Source: https://pyinstaller.org/en/stable/_sources/usage.rst.txt

Command syntax for installing a Version resource into an existing executable using the pyi-set_version utility.

```bash
pyi-set_version version_text_file executable_file
```

--------------------------------

### Command-line invocation of img2gray.py

Source: https://pyinstaller.org/en/stable/feature-notes.html

Example of how the script is invoked from the terminal with multiple image files.

```bash
python3 img2gray.py image1.png image2.png ...
```

--------------------------------

### Using eval_statement

Source: https://pyinstaller.org/en/stable/hooks.html

Example of using eval_statement to execute code and evaluate the output.

```python
databases = eval_statement('''
   import sqlalchemy.databases
   print(sqlalchemy.databases.__all__)
   ''')
for db in databases:
   hiddenimports.append("sqlalchemy.databases." + db)
```

--------------------------------

### Using exec_statement

Source: https://pyinstaller.org/en/stable/hooks.html

Examples of using exec_statement to run Python code in an external interpreter and capture output.

```python
tk_version = exec_statement("from _tkinter import TK_VERSION; print(TK_VERSION)")

mpl_data_dir = exec_statement("import matplotlib; print(matplotlib.get_data_path())")
datas = [ (mpl_data_dir, "") ]
```

--------------------------------

### Frozen application resource tracker invocation

Source: https://pyinstaller.org/en/stable/_sources/common-issues-and-pitfalls.rst.txt

The command-line arguments used by a frozen application to start the resource tracker process.

```bash
my_program -B -S -I -c "from multiprocessing.resource_tracker import main;main(5)"
```

--------------------------------

### Manual macOS bootloader build steps

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Perform these steps if you choose not to use the provided Vagrant build-guest.

```bash
mkdir -p ~/osxcross
tar -C ~/osxcross --xz -xf /vagrant/sdks/osx/osxcross.tar.xz
PATH=~/osxcross/bin/:$PATH
python ./waf all CC=x86_64-apple-darwin15-clang
python ./waf all CC=i386-apple-darwin15-clang
```

--------------------------------

### distribution(name)

Source: https://pyinstaller.org/en/stable/hooks.html

Get distribution information for a given distribution name (i.e., something you would conda install). Returns a Distribution object.

```APIDOC
## distribution(name)

### Description
Get distribution information for a given distribution name (i.e., something you would conda install).

### Method
Function call

### Parameters
- **name** (str) - Required - The name of the distribution.

### Return Type
`Distribution`

### Example
```python
from PyInstaller.utils.hooks import conda_support

dist = conda_support.distribution("numpy")
```
```

--------------------------------

### Customize macOS Info.plist with BUNDLE

Source: https://pyinstaller.org/en/stable/_sources/spec-files.rst.txt

Example of passing an info_plist dictionary to the BUNDLE class to configure application metadata and document types in the Info.plist file.

```python
app = BUNDLE(coll,
         name='myscript.app',
         icon=None,
         bundle_identifier=None,
         version='0.0.1',
         info_plist={
            'NSPrincipalClass': 'NSApplication',
            'NSAppleScriptEnabled': False,
            'CFBundleDocumentTypes': [
                {
                    'CFBundleTypeName': 'My File Format',
                    'CFBundleTypeIconFile': 'MyFileIcon.icns',
                    'LSItemContentTypes': ['com.example.myformat'],
                    'LSHandlerRank': 'Owner'
                    }
                ]
            },
         )
```

--------------------------------

### Equivalent pyinstaller command line for Python code example

Source: https://pyinstaller.org/en/stable/usage.html

This command is the command-line equivalent of the Python code that calls PyInstaller.__main__.run with the arguments 'my_script.py', '--onefile', and '--windowed'.

```bash
pyinstaller my_script.py --onefile --windowed

```

--------------------------------

### Define PyInstaller entry-points in setup.cfg

Source: https://pyinstaller.org/en/stable/_sources/hooks.rst.txt

Register hook directories and test paths by adding entry-points to the setup.cfg file.

```ini
[options.entry_points]
pyinstaller40 =
  hook-dirs = pyi_hooksample.__pyinstaller:get_hook_dirs
  tests     = pyi_hooksample.__pyinstaller:get_PyInstaller_tests
```

--------------------------------

### Add data file via PyInstaller CLI

Source: https://pyinstaller.org/en/stable/_sources/runtime-information.rst.txt

Example of using the --add-data flag to include a data file in the root of the bundle.

```bash
PyInstaller --add-data="/path/to/file.dat:."
```

--------------------------------

### Specify Python interpreter run-time options in spec file

Source: https://pyinstaller.org/en/stable/_sources/spec-files.rst.txt

Creates a list of three-element tuples ('option string', None, 'OPTION') and passes it to EXE before keyword arguments to set permanent Python interpreter run-time options. The example sets the verbose flag ('v') and a warning control option ('W ignore').

```python
options = [
    ('v', None, 'OPTION'),
    ('W ignore', None, 'OPTION'),
]

a = Analysis(
    ...
)
...
exe = EXE(
    pyz,
    a.scripts,
    options,  # <-- the options list, passed to EXE
    exclude_binaries=...
    ...
)
```

--------------------------------

### Windows worker process spawn command

Source: https://pyinstaller.org/en/stable/_sources/common-issues-and-pitfalls.rst.txt

Example of the command-line arguments used by the multiprocessing module to spawn a worker process on Windows.

```bash
python.exe -c "from multiprocessing.spawn import spawn_main; spawn_main(parent_pid=6872, pipe_handle=520)" --multiprocessing-fork
```

--------------------------------

### Install specific PyInstaller branch

Source: https://pyinstaller.org/en/stable/_sources/installation.rst.txt

Install a specific branch of PyInstaller from git, such as the develop branch.

```bash
pip install git+https://github.com/pyinstaller/pyinstaller@develop
```

--------------------------------

### Invoking PyInstaller with optimization flag

Source: https://pyinstaller.org/en/stable/_sources/feature-notes.rst.txt

Example of running PyInstaller as a module with the -OO flag to set the optimization level in versions prior to 6.6.

```bash
python -OO -m PyInstaller <...>
```

--------------------------------

### Build macOS bootloaders with Vagrant

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Set the target environment and build the bootloaders. If the process fails, use the provision command to retry.

```bash
export TARGET=OSX  # make the Vagrantfile build for macOS
vagrant up linux64 && vagrant halt linux64
```

```bash
vagrant provision linux64
```

--------------------------------

### Ctypes library loading issue

Source: https://pyinstaller.org/en/stable/_sources/feature-notes.rst.txt

Example of a Ctypes library load that PyInstaller's older import detection machinery would miss.

```python
from ctypes import *
# This will pass undetected under PyInstaller detect machinery,
# because it's not a direct import.
handle = CDLL("/usr/lib/library.so")
handle.function_call()
```

--------------------------------

### Build macOS SDK and tools with Vagrant

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Use the Vagrantfile to automatically build the SDK and tools. If the process fails, use the provision command to retry.

```bash
vagrant up build-osxcross && vagrant halt build-osxcross
```

```bash
vagrant provision build-osxcross
```

--------------------------------

### Build FreeBSD bootloader with Docker

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Command to run the FreeBSD cross-compiler container and build the bootloader from the repository root.

```bash
docker run -v $(pwd):/io -it freebsd-cross-build bash -c "cd /io/bootloader; ./waf all"
```

--------------------------------

### Add a single README file via command line

Source: https://pyinstaller.org/en/stable/_sources/spec-files.rst.txt

The command line equivalent for adding a data file to the bundle.

```bash
pyinstaller --add-data "src/README.txt:." myscript.py
```

--------------------------------

### Build SDK and tools with Vagrant

Source: https://pyinstaller.org/en/stable/bootloader-building.html

Uses the Vagrantfile to automatically build the SDK and tools required for cross-compilation.

```bash
vagrant up build-osxcross && vagrant halt build-osxcross
```

--------------------------------

### Configure Gtk hooks with Analysis hooksconfig

Source: https://pyinstaller.org/en/stable/_sources/CHANGES.rst.txt

Pass the hooksconfig keyword argument to Analysis to specify which icon sets, themes, and locales to pack with Gtk applications. The example sets icons to Adwaita, themes to Adwaita, and languages to en_GB and zh_CN.

```python
a = Analysis(["my-gtk-app.py"],
                 ...,
                 hooksconfig={
                     "gi": {
                         "icons": ["Adwaita"],
                         "themes": ["Adwaita"],
                         "languages": ["en_GB", "zh_CN"]
                     }
                 },
                 ...)
```

--------------------------------

### Splash target configuration

Source: https://pyinstaller.org/en/stable/_sources/spec-files.rst.txt

The Splash target must be called at build time to display a splash screen. By default, optional text is disabled (text_pos=None). This example shows a Splash instance with text positioned at (10, 50), size 12, and color 'black'.

```python
a = Analysis(...)

splash = Splash('image.png',
                binaries=a.binaries,
                datas=a.datas,
                text_pos=(10, 50),
                text_size=12,
                text_color='black')
```

--------------------------------

### Import shared module in example.spec

Source: https://pyinstaller.org/en/stable/spec-files.html

Configures the spec file to include the directory in the search path and import the shared module to access its variables.

```python
# example.spec

import sys
import os

# SPEC is defined by PyInstaller in the context in which the spec is executed
sys.path.insert(0, os.path.dirname(SPEC))

import common_spec

a = Analysis(
    ['example.py'],
    pathex=[],
    binaries=[],
    datas=common_spec.datas,
...
```

--------------------------------

### Build ARM native binaries with MSVC

Source: https://pyinstaller.org/en/stable/_sources/CHANGES.rst.txt

Use this command to build ARM native binaries on Windows using MSVC.

```bash
python waf --target-arch=64bit-arm all
```

--------------------------------

### Operation not permitted error example

Source: https://pyinstaller.org/en/stable/when-things-go-wrong.html

Example error message when a onefile PyInstaller app fails to run due to 'Operation not permitted'. This can be caused by wrong permissions for /tmp, such as a filesystem mounted with noexec flags.

```text
./hello: error while loading shared libraries: libz.so.1:
failed to map segment from shared object: Operation not permitted

```

--------------------------------

### Windows PowerShell: Force bootloader rebuild during pip install

Source: https://pyinstaller.org/en/stable/bootloader-building.html

Sets environment variables and runs pip commands to uninstall, clear cache, and install PyInstaller from source with bootloader rebuild. Use in Windows PowerShell. Requires prior removal of PyInstaller and cached wheels.

```powershell
$env:PYINSTALLER_COMPILE_BOOTLOADER=1
$env:PYINSTALLER_BOOTLOADER_WAF_ARGS="--example-option=example-value --example-flag"
python -m pip uninstall PyInstaller
python -m pip cache remove PyInstaller
python -m pip install --verbose --no-binary=PyInstaller PyInstaller

```

--------------------------------

### Other (Unix-like): Force bootloader rebuild during pip install

Source: https://pyinstaller.org/en/stable/bootloader-building.html

Sets environment variables and runs pip commands to uninstall, clear cache, and install PyInstaller from source with bootloader rebuild. Use in Unix-like shells (e.g., bash). Requires prior removal of PyInstaller and cached wheels.

```bash
export PYINSTALLER_COMPILE_BOOTLOADER=1
export PYINSTALLER_BOOTLOADER_WAF_ARGS="--example-option=example-value --example-flag"
python -m pip uninstall PyInstaller
python -m pip cache remove PyInstaller
python -m pip install --verbose --no-binary=PyInstaller PyInstaller

```

--------------------------------

### Windows command prompt: Force bootloader rebuild during pip install

Source: https://pyinstaller.org/en/stable/bootloader-building.html

Sets environment variables and runs pip commands to uninstall, clear cache, and install PyInstaller from source with bootloader rebuild. Use in Windows command prompt. Requires prior removal of PyInstaller and cached wheels.

```batch
set PYINSTALLER_COMPILE_BOOTLOADER=1
set "PYINSTALLER_BOOTLOADER_WAF_ARGS=--example-option=example-value --example-flag"
python -m pip uninstall PyInstaller
python -m pip cache remove PyInstaller
python -m pip install --verbose --no-binary=PyInstaller PyInstaller

```

--------------------------------

### Configure PATH for MinGW-w64

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Set the system PATH to include the MinGW binary directory before building the bootloader.

```batch
set PATH=C:\MinGW\bin;%PATH%
```

--------------------------------

### Upgrade PyInstaller

Source: https://pyinstaller.org/en/stable/_sources/installation.rst.txt

Command to upgrade an existing PyInstaller installation to the latest version.

```bash
pip install --upgrade pyinstaller
```

--------------------------------

### Build the combined spec file

Source: https://pyinstaller.org/en/stable/_sources/spec-files.rst.txt

Build the final application bundle using the combined spec file.

```bash
pyinstaller foobarzap.spec
```

--------------------------------

### Collect submodules with collect_submodules

Source: https://pyinstaller.org/en/stable/hooks.html

Example of collecting submodules while filtering out those containing the word 'test'.

```python
# Collect all submodules of Sphinx don't contain the word ``test``.
hiddenimports = collect_submodules(
    "Sphinx", ``filter=lambda name: 'test' not in name)
```

--------------------------------

### Build bootloader for 64-bit Python on AIX

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Set the OBJECT_MODE environment variable to 64 and run the build command.

```bash
export OBJECT_MODE=64
python ./waf all
```

--------------------------------

### Build the bootloader manually

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Run this command within the bootloader directory to compile the bootloader from source.

```bash
python ./waf all
```

--------------------------------

### Identify Python compiler on AIX

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Retrieve the name of the compiler used to build the current Python installation.

```python
python -c "import sysconfig; print(sysconfig.get_config_var('CC'))"
```

--------------------------------

### Build bootloader for 64-bit Python on AIX

Source: https://pyinstaller.org/en/stable/bootloader-building.html

Use these commands when the Python bitness check returned False (64-bit Python). Sets OBJECT_MODE=64 and runs waf to build the bootloader.

```shell
export OBJECT_MODE=64
python ./waf all

```

--------------------------------

### Find PyInstaller scripts path on Windows

Source: https://pyinstaller.org/en/stable/_sources/installation.rst.txt

Python commands to identify the directory where the pyinstaller executable is installed on Windows.

```python
import sysconfig; print(sysconfig.get_path("scripts"))
import site; print(site.USER_BASE + "\\Scripts")
```

--------------------------------

### Add binary file via --add-binary command-line option

Source: https://pyinstaller.org/en/stable/_sources/spec-files.rst.txt

Adds a binary file to the bundle root using the --add-binary command-line option. The source and destination are separated by a colon (':').

```bash
pyinstaller --add-binary "/usr/lib/libiodbc.2.dylib:." myscript.py
```

--------------------------------

### Bundle a windowed application as a single file

Source: https://pyinstaller.org/en/stable/_sources/operating-mode.rst.txt

Use the --onefile and --windowed options to package a script into a single executable file that runs without a console window.

```bash
pyinstaller --onefile --windowed myscript.py
```

--------------------------------

### Build bootloader for 32-bit Python on AIX

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Unset the OBJECT_MODE environment variable and run the build command.

```bash
unset OBJECT_MODE
python ./waf all
```

--------------------------------

### Analyze binary dependencies with pyi-bindepend

Source: https://pyinstaller.org/en/stable/_sources/advanced-topics.rst.txt

Analyzes an executable or DLL and writes its binary dependencies to stdout.

```bash
pyi-bindepend executable_or_dynamic_library
```

--------------------------------

### Traceback for missing Cython module

Source: https://pyinstaller.org/en/stable/_sources/feature-notes.rst.txt

Example of a ModuleNotFoundError occurring when a Cython module fails to import a Python module.

```text
Traceback (most recent call last):
[…]
File "myapp\cython_module.pyx", line 3, in init myapp.cython_module
ModuleNotFoundError: No module named 'csv'
```

--------------------------------

### Build Thin Native Executable on macOS

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Build a thin, native executable on macOS using the waf build command.

```shell
python waf --no-universal2 all
```

--------------------------------

### Bullet point formatting in commit messages

Source: https://pyinstaller.org/en/stable/_sources/development/commit-messages.rst.txt

Example of how to format bullet points within a commit message body.

```text
   * Typically a hyphen or asterisk is used for the bullet, preceded by a
     single space, with blank lines in between, but conventions vary here.

   * Use a hanging indent.
```

--------------------------------

### Frozen application worker process invocation

Source: https://pyinstaller.org/en/stable/_sources/common-issues-and-pitfalls.rst.txt

The command-line arguments used by a frozen application to start a worker process.

```bash
my_program --multiprocessing-fork tracker_fd=6 pipe_handle=8
```

--------------------------------

### package_distribution(name)

Source: https://pyinstaller.org/en/stable/hooks.html

Get distribution information for a package (i.e., something you would import). Returns a Distribution object.

```APIDOC
## package_distribution(name)

### Description
Get distribution information for a package (i.e., something you would import).

### Method
Function call

### Parameters
- **name** (str) - Required - The name of the package.

### Return Type
`Distribution`

### Example
```python
>>> package_distribution("pkg_resources")
Distribution(name="setuptools",
             packages=['easy_install', 'pkg_resources', 'setuptools'])
```
```

--------------------------------

### Find PyInstaller scripts path on UNIX

Source: https://pyinstaller.org/en/stable/_sources/installation.rst.txt

Python commands to identify the directory where the pyinstaller executable is installed on UNIX systems.

```python
import sysconfig; print(sysconfig.get_path("scripts"))
import site; print(site.USER_BASE + "/bin")
```

--------------------------------

### Generate individual spec files

Source: https://pyinstaller.org/en/stable/_sources/spec-files.rst.txt

Use pyi-makespec to generate initial spec files for each application in the bundle.

```bash
pyi-makespec options as appropriate... foo.py

pyi-makespec options as appropriate... bar.py

pyi-makespec options as appropriate... zap.py
```

--------------------------------

### Determine Python architecture on AIX

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Check if the current Python installation is 32-bit. The output is True for 32-bit and False for 64-bit.

```python
python -c "import sys; print(sys.maxsize <= 2**32)"
```

--------------------------------

### Add pyenv configuration to shell startup file

Source: https://pyinstaller.org/en/stable/_sources/development/venv.rst.txt

Adds pyenv to PATH and enables shims, autocompletion, and virtualenv integration in .bashrc or .zshrc.

```bash
# Add 'pyenv' to PATH.
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"

# Enable shims and autocompletion for pyenv.
eval "$(pyenv init -)"
# Load pyenv-virtualenv automatically by adding
# # the following to ~/.zshrc:
#
eval "$(pyenv virtualenv-init -)"
```

--------------------------------

### Analysis hooksconfig configuration

Source: https://pyinstaller.org/en/stable/_sources/hooks-config.rst.txt

Example of configuring the matplotlib hook within the Analysis object, showing how to set the backends option.

```python
a = Analysis(
    ["my-matplotlib-app.py"],
    ...,
    hooksconfig={
        "matplotlib": {
            "backends": "auto",  # auto-detect; the default behavior
            # "backends": "all",  # collect all backends
            # "backends": "TkAgg",  # collect a specific backend
            # "backends": ["TkAgg", "Qt5Agg"],  # collect multiple backends
        },
    },
    ...,
)
```

--------------------------------

### Splash.__init__

Source: https://pyinstaller.org/en/stable/spec-files.html

Constructor for the Splash target, which bundles resources for a splash screen into a file included in the CArchive. Requires image file, binaries TOC, and datas TOC.

```APIDOC
## Splash.__init__

### Description
Creates a Splash target for displaying a splash screen by the bootloader. Bundles required resources into a file included in the CArchive. The splash target has two outputs: itself and splash.binaries, both must be passed to other build targets.

### Method
Constructor

### Parameters
#### Required Parameters
- **image_file** (str) - Required - Path-like object to the image. Only PNG format supported. If PIL is installed, other formats are converted automatically. On Windows, the color 'magenta'/'#ff00ff' must not be used. If PIL is installed and image is larger than max_img_size, it is resized.
- **binaries** (list) - Required - TOC list of binaries from Analysis. Includes extension modules and binary dependencies. Required to determine if tkinter is used.
- **datas** (list) - Required - TOC list of data from Analysis. Includes data-file dependencies. Required to check if splash screen requirements can be bundled.

#### Optional Parameters (kwargs)
- **text_pos** (tuple) - Optional - Position of optional text. Default is None (disabled). Example: (10, 50)
- **text_size** (int) - Optional - Font size of text. Example: 12
- **text_color** (str) - Optional - Color of text. Example: 'black'

### Request Example
```
a = Analysis(...)
splash = Splash('image.png',
                binaries=a.binaries,
                datas=a.datas,
                text_pos=(10, 50),
                text_size=12,
                text_color='black')
```

### Response
Returns a Splash object. The object itself and its binaries attribute must be passed to EXE and COLLECT targets.
```

--------------------------------

### Exclude GStreamer plugin

Source: https://pyinstaller.org/en/stable/_sources/hooks-config.rst.txt

Example of using hooksconfig to exclude the opencv GStreamer plugin to reduce the size of the frozen application.

```python
a = Analysis(
    ["my-gstreamer-app.py"],
    ...,
    hooksconfig={
        "gstreamer": {
            "exclude_plugins": [
                "opencv",
            ],
        },
    },
    ...,
)
```

--------------------------------

### Use custom Sphinx roles

Source: https://pyinstaller.org/en/stable/_sources/development/documentation.rst.txt

Examples of using custom roles to link to commits and GitHub issues within reStructuredText.

```rst
:commit:`a1b2c3d4e5f6a7b8c9`
```

```rst
:issue:`123`
```

--------------------------------

### Rebuild Bootloader on Windows (Command Prompt)

Source: https://pyinstaller.org/en/stable/_sources/bootloader-building.rst.txt

Use these commands in a Windows Command Prompt to force a rebuild of the bootloader.

```batch
set PYINSTALLER_COMPILE_BOOTLOADER=1
set "PYINSTALLER_BOOTLOADER_WAF_ARGS=--example-option=example-value --example-flag"
python -m pip uninstall PyInstaller
python -m pip cache remove PyInstaller
python -m pip install --verbose --no-binary=PyInstaller PyInstaller
```

--------------------------------

### Build Windows ARM64 bootloaders with Clang

Source: https://pyinstaller.org/en/stable/_sources/CHANGES.rst.txt

Use this command to build Windows ARM64 bootloaders using an ARM build of clang.

```bash
python waf --target-arch=64bit-arm --clang all
```

--------------------------------

### Retrieve distribution information via package_distribution

Source: https://pyinstaller.org/en/stable/hooks.html

Use package_distribution to get distribution details based on the importable package name.

```python
>>> package_distribution("pkg_resources")
Distribution(name="setuptools",
             packages=['easy_install', 'pkg_resources', 'setuptools'])
```

--------------------------------

### files(name, dependencies=False, excludes=None)

Source: https://pyinstaller.org/en/stable/hooks.html

List all files belonging to a distribution. Optionally recursively collect files of dependencies.

```APIDOC
## files(name, dependencies=False, excludes=None)

### Description
List all files belonging to a distribution. If dependencies is True, recursively collect files of dependencies too.

### Method
Function call

### Parameters
- **name** (str) - Required - The name of the distribution.
- **dependencies** (bool) - Optional - Recursively collect files of dependencies too.
- **excludes** (Optional[list]) - Optional - Distributions to ignore if dependencies is true.

### Return Type
`List[PackagePath]`

### Returns
All filenames belonging to the given distribution.

### Example
```python
files = conda_support.files("numpy")
```
```

--------------------------------

### Spec file with argparse for custom --debug flag

Source: https://pyinstaller.org/en/stable/spec-files.html

Use this spec file to support different build modes (debug vs production) from the same spec file. Invoke with 'pyinstaller example.spec -- --debug' for a onedir app with console enabled, or 'pyinstaller example.spec' for a onefile console-less app. Using argparse, 'pyinstaller example.spec -- --help' displays the spec options.

```python
# example.spec

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--debug", action="store_true")
options = parser.parse_args()

a = Analysis(
    ['example.py'],
)
pyz = PYZ(a.pure)

if options.debug:
    exe = EXE(
        pyz,
        a.scripts,
        exclude_binaries=True,
        name='example',
    )
    coll = COLLECT(
        exe,
        a.binaries,
        a.datas,
        name='example_debug',
    )
else:
    exe = EXE(
        pyz,
        a.scripts,
        a.binaries,
        a.datas,
        name='example',
        console=False,
    )

```

--------------------------------

### Create a TOC list for binary modules

Source: https://pyinstaller.org/en/stable/_sources/advanced-topics.rst.txt

Creates a TOC list for binary modules by excluding source files and setting the typecode to EXTENSION.

```python
cython_mods = Tree('..src/cy_mods', excludes=['*.pyx', '*.py', '*.pyc'], typecode='EXTENSION')
```

--------------------------------

### Build bootloader for 32-bit Python on AIX

Source: https://pyinstaller.org/en/stable/bootloader-building.html

Use these commands when the Python bitness check returned True (32-bit Python). Unsets OBJECT_MODE and runs waf to build the bootloader.

```shell
unset OBJECT_MODE
python ./waf all

```

--------------------------------

### Define hidden imports in a hook

Source: https://pyinstaller.org/en/stable/_sources/hooks.rst.txt

A simple hook file example that ensures a specific module is collected by assigning it to the hiddenimports list.

```python
hiddenimports = ["xml.dom.minidom"]
```

--------------------------------

### List distribution files shortcut

Source: https://pyinstaller.org/en/stable/hooks.html

When dependencies=False, the files method acts as a shortcut to accessing the distribution's files attribute directly.

```python
conda_support.distribution(name).files
```

--------------------------------

### Frozen application Windows worker process invocation

Source: https://pyinstaller.org/en/stable/_sources/common-issues-and-pitfalls.rst.txt

The command-line arguments used by a frozen application to start a worker process on Windows.

```bash
my_program.exe --multiprocessing-fork parent_pid=8752 pipe_handle=1552
```

--------------------------------

### Run core test suite

Source: https://pyinstaller.org/en/stable/_sources/development/testing.rst.txt

Execute the core unit and functional tests.

```bash
pytest tests/unit tests/functional
```
Tokens:
Raw