0
# PyInstaller
1

2
PyInstaller is a mature Python application bundling tool that converts Python scripts and their dependencies into standalone executable packages. It analyzes Python code to discover all required modules and libraries, then collects copies of those files along with the Python interpreter into a single folder or executable file.
3

4
## Package Information
5

6
- **Package Name**: pyinstaller
7
- **Language**: Python
8
- **Installation**: `pip install pyinstaller`
9
- **Documentation**: https://pyinstaller.org/
10

11
## Core Imports
12

13
```python
14
import PyInstaller
15
```
16

17
For programmatic usage:
18

19
```python
20
from PyInstaller import run
21
from PyInstaller.building.build_main import Analysis
22
from PyInstaller.building.api import PYZ, EXE, COLLECT
23
```
24

25
For hook development:
26

27
```python
28
from PyInstaller.utils.hooks import collect_submodules, collect_data_files
29
```
30

31
## Basic Usage
32

33
### Command Line Interface
34

35
```bash
36
# Create a standalone executable from a Python script
37
pyinstaller myscript.py
38

39
# Create a one-file executable
40
pyinstaller --onefile myscript.py
41

42
# Create a windowed application (no console)
43
pyinstaller --windowed myapp.py
44

45
# Add additional data files
46
pyinstaller --add-data "data/*:data" myscript.py
47

48
# Exclude modules to reduce size
49
pyinstaller --exclude-module matplotlib myscript.py
50
```
51

52
### Programmatic Usage
53

54
```python
55
from PyInstaller import run
56

57
# Run PyInstaller programmatically
58
run(['myscript.py', '--onefile', '--name=MyApp'])
59
```
60

61
### Spec File Approach
62

63
```python
64
# myapp.spec
65
from PyInstaller.building.build_main import Analysis
66
from PyInstaller.building.api import PYZ, EXE
67

68
a = Analysis(
69
    ['myapp.py'],
70
    pathex=[],
71
    binaries=[],
72
    datas=[('data/', 'data/')],
73
    hiddenimports=['hidden_module'],
74
    hookspath=[],
75
    hooksconfig={},
76
    runtime_hooks=[],
77
    excludes=[],
78
    win_no_prefer_redirects=False,
79
    win_private_assemblies=False,
80
    cipher=None,
81
    noarchive=False
82
)
83

84
pyz = PYZ(a.pure, a.zipped_data, cipher=None)
85

86
exe = EXE(
87
    pyz,
88
    a.scripts,
89
    a.binaries,
90
    a.zipfiles,
91
    a.datas,
92
    [],
93
    name='MyApp',
94
    debug=False,
95
    bootloader_ignore_signals=False,
96
    strip=False,
97
    upx=True,
98
    upx_exclude=[],
99
    runtime_tmpdir=None,
100
    console=True
101
)
102
```
103

104
## Architecture
105

106
PyInstaller uses a multi-stage build process:
107

108
1. **Analysis Phase**: Discovers all dependencies through import analysis and hook execution
109
2. **Collection Phase**: Gathers all required files (Python modules, extensions, data files)
110
3. **Packaging Phase**: Creates archives and bundles files with bootloader
111
4. **Executable Generation**: Produces final standalone executable or directory
112

113
The bootloader is a small C program that extracts and executes the bundled Python application at runtime, providing cross-platform compatibility without requiring Python installation on target systems.
114

115
## Capabilities
116

117
### CLI Interface
118

119
Command-line interface for creating standalone executables from Python applications with extensive configuration options for output format, optimization, and bundling behavior.
120

121
```python { .api }
122
def run(pyi_args=None, pyi_config=None):
123
    """
124
    Main entry point for running PyInstaller programmatically.
125
    
126
    Args:
127
        pyi_args (list): Command-line arguments (defaults to sys.argv[1:])
128
        pyi_config (dict): Configuration dictionary for multiple builds
129
    """
130
```
131

132
[CLI Interface](./cli-interface.md)
133

134
### Spec File Building Classes
135

136
Core classes used in .spec files to define the build process, including dependency analysis, archive creation, and executable generation.
137

138
```python { .api }
139
class Analysis:
140
    """Performs dependency analysis of Python scripts."""
141
    def __init__(self, scripts, pathex=[], binaries=[], datas=[], 
142
                 hiddenimports=[], hookspath=[], runtime_hooks=[], 
143
                 excludes=[], **kwargs): ...
144

145
class PYZ:
146
    """Creates zlib-compressed archive of compiled Python modules."""
147
    def __init__(self, *tocs, name=None): ...
148

149
class EXE:
150
    """Creates final executable from PKG and bootloader."""
151
    def __init__(self, *args, name='', console=True, debug=False, **kwargs): ...
152

153
class COLLECT:
154
    """Collects files into directory for onedir distribution."""
155
    def __init__(self, *args, name='', strip_binaries=False, **kwargs): ...
156
```
157

158
[Spec File Classes](./spec-file-classes.md)
159

160
### Hook Development Utilities
161

162
Functions for writing PyInstaller hooks to handle special cases in dependency collection, including module discovery, data file collection, and metadata handling.
163

164
```python { .api }
165
def collect_submodules(package, filter=None, on_error="warn once"):
166
    """Recursively collect all submodules of a package."""
167

168
def collect_data_files(package, include_py_files=False, subdir=None, 
169
                      excludes=None, includes=None):
170
    """Collect data files from package installation."""
171

172
def collect_all(package_name, include_py_files=True, **kwargs):
173
    """Collect all components for a package."""
174

175
def can_import_module(module_name):
176
    """Test if module can be imported."""
177
```
178

179
[Hook Development](./hook-development.md)
180

181
### CLI Utilities
182

183
Command-line tools for archive inspection, dependency analysis, version handling, and spec file generation.
184

185
```python { .api }
186
# Console scripts available as commands:
187
# pyi-archive_viewer - Interactive archive viewer
188
# pyi-bindepend - Binary dependency analysis  
189
# pyi-grab_version - Windows version extraction
190
# pyi-makespec - Spec file generation
191
# pyi-set_version - Windows version setting
192
```
193

194
[CLI Utilities](./cli-utilities.md)
195

196
### Platform-Specific Features
197

198
Windows and macOS specific functionality including icon handling, version resources, manifest embedding, code signing, and app bundle creation.
199

200
```python { .api }
201
# Windows utilities (PyInstaller.utils.win32)
202
# - icon: Icon file handling
203
# - versioninfo: Version resource utilities
204
# - winmanifest: Manifest handling
205

206
# macOS utilities (PyInstaller.building.osx)
207
class BUNDLE:
208
    """Creates macOS application bundle (.app)."""
209
    def __init__(self, *args, name='', icon=None, bundle_identifier=None, **kwargs): ...
210
```
211

212
[Platform Features](./platform-features.md)
213

214
## Constants and Configuration
215

216
```python { .api }
217
# Version and path constants
218
__version__: str  # PyInstaller version
219
HOMEPATH: str     # PyInstaller home directory  
220
PLATFORM: str     # Platform identifier
221
DEFAULT_DISTPATH: str   # Default output directory (./dist)
222
DEFAULT_SPECPATH: str   # Default spec file directory (.)
223
DEFAULT_WORKPATH: str   # Default working directory (./build)
224
```
225

226
## Exception Classes
227

228
```python { .api }
229
class ExecCommandFailed(SystemExit):
230
    """Command execution failure."""
231

232
class HookError(Exception):
233
    """Base class for hook-related errors."""
234

235
class PythonLibraryNotFoundError(IOError):
236
    """Python shared library not found."""
237

238
class RemovedCipherFeatureError(SystemExit):
239
    """Deprecated cipher feature usage."""
240
```