0
# CLI Interface
1

2
PyInstaller's command-line interface provides comprehensive options for creating standalone executables from Python applications. The CLI handles everything from basic script bundling to complex multi-file applications with custom configurations.
3

4
## Capabilities
5

6
### Main Command
7

8
The primary `pyinstaller` command analyzes Python scripts and creates standalone executables.
9

10
```python { .api }
11
def run(pyi_args=None, pyi_config=None):
12
    """
13
    Main entry point for running PyInstaller programmatically.
14
    
15
    Args:
16
        pyi_args (list, optional): Command-line arguments. If None, uses sys.argv[1:]
17
        pyi_config (dict, optional): Configuration dictionary for multiple builds
18
        
19
    Raises:
20
        SystemExit: On invalid arguments or build failure
21
        RecursionError: When recursion limit exceeded during analysis
22
        KeyboardInterrupt: On user cancellation
23
    """
24
```
25

26
### Basic Usage Patterns
27

28
#### Single File Executable
29
Create a standalone executable that unpacks itself when run:
30

31
```bash
32
pyinstaller --onefile myscript.py
33
```
34

35
#### Directory Distribution  
36
Create a directory containing the executable and all dependencies:
37

38
```bash
39
pyinstaller --onedir myscript.py
40
```
41

42
#### Windowed Application
43
Create an application without console window (Windows/macOS):
44

45
```bash
46
pyinstaller --windowed myapp.py
47
```
48

49
### File and Data Options
50

51
#### Adding Data Files
52
Include additional data files in the bundle:
53

54
```bash
55
# Single file
56
pyinstaller --add-data "config.ini:." myscript.py
57

58
# Directory (Unix)  
59
pyinstaller --add-data "data/*:data" myscript.py
60

61
# Directory (Windows)
62
pyinstaller --add-data "data/*;data" myscript.py
63
```
64

65
#### Adding Binary Files
66
Include binary dependencies:
67

68
```bash
69
pyinstaller --add-binary "libs/mylib.so:libs" myscript.py
70
```
71

72
#### Hidden Imports
73
Force inclusion of modules not detected automatically:
74

75
```bash
76
pyinstaller --hidden-import scipy.integrate myscript.py
77
```
78

79
#### Module Exclusion
80
Exclude modules to reduce bundle size:
81

82
```bash
83
pyinstaller --exclude-module matplotlib myscript.py
84
```
85

86
### Output Configuration
87

88
#### Custom Names and Paths
89
Specify output names and directories:
90

91
```bash
92
# Custom executable name
93
pyinstaller --name MyApplication myscript.py
94

95
# Custom output directory
96
pyinstaller --distpath /path/to/output myscript.py
97

98
# Custom working directory  
99
pyinstaller --workpath /tmp/pyinstaller myscript.py
100

101
# Custom spec file location
102
pyinstaller --specpath /path/to/specs myscript.py
103
```
104

105
#### Clean Build
106
Remove output and working directories before building:
107

108
```bash
109
pyinstaller --clean myscript.py
110
```
111

112
### Optimization Options
113

114
#### UPX Compression
115
Compress binaries using UPX:
116

117
```bash
118
# Enable UPX for all binaries
119
pyinstaller --upx-dir /usr/local/bin myscript.py
120

121
# Exclude specific files from UPX
122
pyinstaller --upx-exclude vcruntime140.dll myscript.py
123
```
124

125
#### Debug Strip
126
Remove debug symbols from binaries:
127

128
```bash
129
pyinstaller --strip myscript.py
130
```
131

132
### Advanced Configuration
133

134
#### Custom Hooks
135
Specify additional hook directories:
136

137
```bash
138
pyinstaller --additional-hooks-dir /path/to/hooks myscript.py
139
```
140

141
#### Runtime Hooks
142
Add runtime hooks that execute at application startup:
143

144
```bash
145
pyinstaller --runtime-hook runtime_hook.py myscript.py
146
```
147

148
#### Path Extensions
149
Add directories to Python path during analysis:
150

151
```bash
152
pyinstaller --paths /extra/python/path myscript.py
153
```
154

155
### Platform-Specific Options
156

157
#### Windows Options
158
```bash
159
# Request administrator privileges
160
pyinstaller --uac-admin myscript.py
161

162
# Add version resource file
163
pyinstaller --version-file version.txt myscript.py
164

165
# Add custom icon
166
pyinstaller --icon app.ico myscript.py
167

168
# Add Windows manifest
169
pyinstaller --manifest manifest.xml myscript.py
170
```
171

172
#### macOS Options
173
```bash
174
# Add application icon
175
pyinstaller --icon app.icns myscript.py
176

177
# Enable macOS app bundle creation
178
pyinstaller --windowed --osx-bundle-identifier com.example.app myscript.py
179

180
# Add entitlements file
181
pyinstaller --osx-entitlements-file entitlements.plist myscript.py
182
```
183

184
### Logging and Debug Options
185

186
#### Verbosity Control
187
```bash
188
# Increase verbosity
189
pyinstaller --log-level DEBUG myscript.py
190

191
# Quiet output
192
pyinstaller --log-level WARN myscript.py
193
```
194

195
#### Debug Information
196
```bash
197
# Include debug information in executable
198
pyinstaller --debug all myscript.py
199

200
# Debug imports only
201
pyinstaller --debug imports myscript.py
202
```
203

204
### Spec File Generation
205

206
Create a .spec file without building:
207

208
```bash
209
pyinstaller --specpath . --name MyApp --onefile myscript.py --noconfirm
210
```
211

212
Then edit the .spec file and build with:
213

214
```bash
215
pyinstaller MyApp.spec
216
```
217

218
### Common Command Combinations
219

220
#### Production Desktop App
221
```bash
222
pyinstaller \
223
  --onefile \
224
  --windowed \
225
  --name "My Application" \
226
  --icon app.ico \
227
  --add-data "config/*:config" \
228
  --hidden-import pkg_resources.py2_warn \
229
  --clean \
230
  main.py
231
```
232

233
#### Development Build
234
```bash
235
pyinstaller \
236
  --onedir \
237
  --console \
238
  --debug all \
239
  --clean \
240
  main.py
241
```
242

243
#### Minimal Size Build
244
```bash
245
pyinstaller \
246
  --onefile \
247
  --strip \
248
  --upx-dir /usr/bin \
249
  --exclude-module matplotlib \
250
  --exclude-module numpy \
251
  main.py
252
```
253

254
## Exit Codes
255

256
- **0**: Success
257
- **1**: General error (invalid arguments, build failure)
258
- **2**: Keyboard interrupt (Ctrl+C)
259

260
## Environment Variables
261

262
- **`PYINSTALLER_COMPILE_BOOTLOADER`**: Force bootloader compilation
263
- **`PYINSTALLER_BOOTLOADER_WAF_ARGS`**: Additional WAF arguments for bootloader compilation