0
# Command Line Interface
1

2
Nuitka provides powerful command-line tools for compiling Python code to C and creating optimized executables or modules. The CLI offers comprehensive control over compilation modes, optimization levels, and output formats.
3

4
## Capabilities
5

6
### Main Compiler Command
7

8
The primary Nuitka compiler command that transforms Python scripts and modules into optimized C code and executables.
9

10
```bash { .api }
11
nuitka [options] script.py
12

13
# Common options:
14
--standalone                 # Create standalone executable with dependencies
15
--module                    # Create extension module instead of executable  
16
--package                   # Create package with multiple modules
17
--output-dir=DIR            # Specify output directory
18
--output-filename=NAME      # Set output filename
19
--include-package=PKG       # Include specific packages
20
--include-module=MOD        # Include specific modules
21
--plugin-enable=PLUGIN      # Enable specific plugins
22
--python-flag=FLAG          # Set Python runtime flags
23
--verbose                   # Enable verbose output
24
--debug                     # Include debug information
25
--optimize                  # Enable C-level optimizations
26
--lto=yes/no               # Link-time optimization
27
--jobs=N                   # Parallel compilation jobs
28
```
29

30
**Usage Examples:**
31

32
```bash
33
# Create standalone executable
34
nuitka --standalone --output-dir=dist myapp.py
35

36
# Compile as extension module
37
nuitka --module --output-dir=build myextension.py
38

39
# Compile with specific plugins and optimizations
40
nuitka --standalone --plugin-enable=tk-inter --plugin-enable=numpy --optimize myapp.py
41

42
# Include additional packages and modules
43
nuitka --standalone --include-package=requests --include-module=ssl myapp.py
44
```
45

46
### Run Mode Command
47

48
Execute Python scripts with Nuitka compilation for immediate performance benefits without creating persistent output files.
49

50
```bash { .api }
51
nuitka-run [nuitka-options] script.py [script-arguments]
52

53
# Options are same as nuitka command
54
--module-cache-dir=DIR      # Cache compiled modules
55
--python-flag=FLAG          # Python runtime flags
56
--verbose                   # Verbose compilation output
57
```
58

59
**Usage Examples:**
60

61
```bash
62
# Run script with Nuitka compilation
63
nuitka-run myscript.py arg1 arg2
64

65
# Run with caching for faster subsequent runs
66
nuitka-run --module-cache-dir=cache myscript.py
67

68
# Run with verbose output
69
nuitka-run --verbose myscript.py
70
```
71

72
### Commercial Decryption Tool
73

74
Decrypt and manage commercial Nuitka plugins and encrypted data files (requires commercial license).
75

76
```bash { .api }
77
nuitka-decrypt [options] encrypted-file
78

79
# Options:
80
--output=FILE               # Decrypted output file
81
--key=KEY                  # Decryption key
82
--verbose                  # Verbose output
83
```
84

85
**Usage Examples:**
86

87
```bash
88
# Decrypt commercial plugin
89
nuitka-decrypt --output=plugin.py encrypted-plugin.plk
90

91
# Decrypt with specific key
92
nuitka-decrypt --key=mykey --output=data.py encrypted-data.tmd
93
```
94

95
## Compilation Modes
96

97
### Standalone Mode
98

99
Creates self-contained executables with all dependencies included.
100

101
```bash
102
nuitka --standalone myapp.py
103
```
104

105
- Includes Python interpreter and all required modules
106
- No external Python installation required on target system
107
- Larger file size but maximum portability
108
- Automatic dependency detection and inclusion
109

110
### Module Mode  
111

112
Compiles Python modules as C extension modules.
113

114
```bash
115
nuitka --module mymodule.py
116
```
117

118
- Creates .so (Linux/macOS) or .pyd (Windows) extension
119
- Can be imported like regular Python modules
120
- Faster execution than interpreted Python
121
- Maintains full Python API compatibility
122

123
### Package Mode
124

125
Compiles entire Python packages with multiple modules.
126

127
```bash
128
nuitka --package mypackage/
129
```
130

131
- Handles package hierarchies and __init__.py files
132
- Preserves package structure and imports
133
- Optimizes inter-module calls within package
134
- Suitable for large codebases and libraries
135

136
## Plugin System Integration
137

138
### Standard Plugins
139

140
Enable support for common third-party packages through built-in plugins.
141

142
```bash
143
# Enable specific plugins
144
nuitka --plugin-enable=tk-inter --plugin-enable=numpy --standalone myapp.py
145

146
# Common standard plugins:
147
--plugin-enable=tk-inter     # Tkinter GUI support
148
--plugin-enable=qt-plugins   # Qt framework support  
149
--plugin-enable=numpy        # NumPy scientific computing
150
--plugin-enable=matplotlib   # Matplotlib plotting
151
--plugin-enable=pyside2      # PySide2 Qt bindings
152
--plugin-enable=django       # Django web framework
153
--plugin-enable=multiprocessing  # Multiprocessing support
154
```
155

156
### Plugin Options
157

158
Configure plugin behavior with specific options.
159

160
```bash
161
# Plugin-specific configuration
162
nuitka --plugin-enable=qt-plugins --plugin-qt-plugins=platforms,imageformats myapp.py
163

164
# Data file inclusion
165
nuitka --include-data-files=data/ --include-data-dir=resources/ myapp.py
166
```
167

168
## Output Control
169

170
### File and Directory Options
171

172
Control where and how Nuitka generates output files.
173

174
```bash
175
# Output directory control
176
nuitka --output-dir=build --standalone myapp.py
177

178
# Custom output filename
179
nuitka --output-filename=myexe --standalone myapp.py
180

181
# Remove build directory after compilation
182
nuitka --remove-output --standalone myapp.py
183
```
184

185
### Debug and Information Options
186

187
Control debug information and compilation verbosity.
188

189
```bash
190
# Debug information
191
nuitka --debug --standalone myapp.py
192

193
# Verbose compilation output
194
nuitka --verbose --show-progress --standalone myapp.py
195

196
# Show included modules
197
nuitka --show-modules --standalone myapp.py
198

199
# Generate compilation report
200
nuitka --report=compilation-report.xml --standalone myapp.py
201
```
202

203
## Performance Options
204

205
### Optimization Control
206

207
Configure C-level optimizations and compilation settings.
208

209
```bash
210
# Enable optimizations
211
nuitka --optimize --lto=yes --standalone myapp.py
212

213
# Control parallel compilation
214
nuitka --jobs=4 --standalone myapp.py
215

216
# Profile guided optimization
217
nuitka --pgo --standalone myapp.py
218
```
219

220
### Memory and Resource Options
221

222
Manage memory usage and resource inclusion during compilation.
223

224
```bash  
225
# Memory usage control
226
nuitka --low-memory --standalone myapp.py
227

228
# Resource inclusion
229
nuitka --include-data-files=config.json --include-data-dir=assets/ myapp.py
230
```
231

232
## Platform-Specific Options
233

234
### Windows Options
235

236
Windows-specific compilation and executable options.
237

238
```bash
239
# Windows console/GUI modes
240
nuitka --windows-disable-console --standalone myapp.py
241

242
# Windows icon and version info
243
nuitka --windows-icon=icon.ico --windows-company-name="My Company" --standalone myapp.py
244

245
# Windows service mode
246
nuitka --windows-service --standalone myservice.py
247
```
248

249
### macOS Options
250

251
macOS-specific bundling and signing options.
252

253
```bash
254
# macOS app bundle creation
255
nuitka --macos-create-app-bundle --standalone myapp.py
256

257
# Code signing
258
nuitka --macos-sign-identity="Developer ID" --standalone myapp.py
259
```
260

261
### Linux Options
262

263
Linux-specific compilation and packaging options.
264

265
```bash
266
# Linux-specific optimizations
267
nuitka --linux-onefile-icon=icon.png --standalone myapp.py
268
```
269

270
## Error Handling
271

272
Common CLI error scenarios and resolution:
273

274
- **Module Not Found**: Use `--include-module` or `--include-package` to explicitly include dependencies
275
- **Plugin Errors**: Verify plugin names with `--plugin-list` and check plugin-specific requirements
276
- **Compilation Failures**: Use `--verbose` and `--debug` for detailed error diagnostics
277
- **Import Errors**: Check Python path and ensure all dependencies are installed
278
- **Platform Errors**: Verify C compiler installation and platform-specific requirements
279

280
## Environment Variables
281

282
Control Nuitka behavior through environment variables:
283

284
```bash
285
# Compiler selection
286
export CC=gcc
287
export CXX=g++
288

289
# Python path modification
290
export PYTHONPATH=/custom/path:$PYTHONPATH
291

292
# Nuitka-specific variables
293
export NUITKA_CACHE_DIR=/tmp/nuitka-cache
294
export NUITKA_PLUGINS_PATH=/custom/plugins
295
```