0
# Build Tools and Distribution
1
2
Command-line tools and utilities for building distributable Eel applications using PyInstaller integration.
3
4
## Capabilities
5
6
### PyInstaller Integration CLI
7
8
Build distributable executables from Eel applications using the built-in PyInstaller integration.
9
10
```python { .api }
11
# Command-line interface (python -m eel)
12
python -m eel main_script web_folder [PyInstaller arguments...]
13
```
14
15
**Parameters:**
16
- `main_script`: str - Main Python file containing the Eel application
17
- `web_folder`: str - Directory containing web files (HTML, CSS, JS, etc.)
18
- `[PyInstaller arguments...]`: Additional arguments passed to PyInstaller
19
20
**Usage Examples:**
21
22
```bash
23
# Basic executable build
24
python -m eel hello.py web
25
26
# Build with additional PyInstaller flags
27
python -m eel my_app.py frontend --onefile --noconsole
28
29
# Exclude specific modules
30
python -m eel app.py web --exclude-module win32com --exclude-module numpy
31
32
# Build with custom name and icon
33
python -m eel main.py static --name "My App" --icon app.ico
34
35
# One-file executable without console
36
python -m eel script.py web_files --onefile --noconsole --windowed
37
```
38
39
### Automatic PyInstaller Configuration
40
41
The CLI automatically configures PyInstaller with required Eel-specific settings:
42
43
- **Hidden Import**: Automatically includes `bottle_websocket` dependency
44
- **Data Files**: Bundles `eel.js` file for browser communication
45
- **Web Assets**: Includes entire web folder in executable
46
- **Cross-platform**: Works on Windows, macOS, and Linux
47
48
### Build Process Details
49
50
The CLI performs these steps automatically:
51
52
1. **Dependency Detection**: Identifies required hidden imports for Eel functionality
53
2. **Asset Bundling**: Packages web folder and eel.js into executable
54
3. **PyInstaller Execution**: Runs PyInstaller with optimized configuration
55
4. **Output Generation**: Creates executable in `dist/` directory
56
57
**Example Build Output:**
58
59
```bash
60
$ python -m eel my_app.py web --onefile
61
Building executable with main script 'my_app.py' and web folder 'web'...
62
63
Running:
64
pyinstaller my_app.py --hidden-import bottle_websocket --add-data eel.js;eel --add-data web;web --onefile
65
66
[PyInstaller output...]
67
```
68
69
### Common PyInstaller Options
70
71
Frequently used PyInstaller flags with Eel applications:
72
73
```bash
74
# Application options
75
--onefile # Create single executable file
76
--onedir # Create directory with executable and dependencies
77
--noconsole # Hide console window (Windows)
78
--windowed # Same as --noconsole
79
80
# Debugging options
81
--debug=all # Enable debug output
82
--console # Show console for debugging
83
84
# Optimization options
85
--exclude-module MODULE # Exclude unnecessary modules
86
--strip # Strip debug symbols (Linux/macOS)
87
88
# Customization options
89
--name NAME # Executable name
90
--icon ICON # Application icon
91
--version-file FILE # Version information file (Windows)
92
```
93
94
### Development Workflow
95
96
Recommended workflow for building Eel applications:
97
98
```bash
99
# 1. Development phase - test locally
100
python my_app.py
101
102
# 2. Testing phase - build directory version
103
python -m eel my_app.py web --onedir
104
105
# 3. Distribution phase - build single file
106
python -m eel my_app.py web --onefile --noconsole
107
108
# 4. Final release - with custom branding
109
python -m eel my_app.py web --onefile --noconsole --name "My App" --icon app.ico
110
```
111
112
### Troubleshooting Common Issues
113
114
**Missing Dependencies:**
115
```bash
116
# Include additional hidden imports
117
python -m eel app.py web --hidden-import your_module
118
119
# Include data files manually
120
python -m eel app.py web --add-data "path/to/file;destination"
121
```
122
123
**Large File Sizes:**
124
```bash
125
# Exclude unnecessary modules
126
python -m eel app.py web --exclude-module tkinter --exclude-module matplotlib
127
```
128
129
**Runtime Errors:**
130
```bash
131
# Build with console for debugging
132
python -m eel app.py web --console
133
134
# Enable debug mode
135
python -m eel app.py web --debug=all
136
```
137
138
## Virtual Environment Considerations
139
140
When using virtual environments, ensure PyInstaller uses the correct Python environment:
141
142
```bash
143
# Activate virtual environment first
144
source venv/bin/activate # Linux/macOS
145
# or
146
venv\Scripts\activate # Windows
147
148
# Then build
149
python -m eel my_app.py web --onefile
150
```
151
152
## Distribution Best Practices
153
154
### File Organization
155
156
```
157
my_eel_app/
158
├── main.py # Main application script
159
├── web/ # Web assets directory
160
│ ├── index.html
161
│ ├── style.css
162
│ └── script.js
163
├── requirements.txt # Python dependencies
164
└── build.bat # Build script
165
```
166
167
### Build Script Example
168
169
```bash
170
#!/bin/bash
171
# build.sh - Automated build script
172
173
echo "Building Eel application..."
174
175
# Clean previous builds
176
rm -rf build/ dist/
177
178
# Build executable
179
python -m eel main.py web \
180
--onefile \
181
--noconsole \
182
--name "My Eel App" \
183
--icon assets/app.ico \
184
--exclude-module tkinter \
185
--exclude-module matplotlib
186
187
echo "Build completed. Executable in dist/ directory."
188
```