tessl/pypi-eel

For little HTML GUI applications, with easy Python/JS interop

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Build Tools and Distribution

Name: tessl/pypi-eel
Author: tessl

Command-line tools and utilities for building distributable Eel applications using PyInstaller integration.

Capabilities

PyInstaller Integration CLI

Build distributable executables from Eel applications using the built-in PyInstaller integration.

# Command-line interface (python -m eel)
python -m eel main_script web_folder [PyInstaller arguments...]

Parameters:

main_script: str - Main Python file containing the Eel application
web_folder: str - Directory containing web files (HTML, CSS, JS, etc.)
[PyInstaller arguments...]: Additional arguments passed to PyInstaller

Usage Examples:

# Basic executable build
python -m eel hello.py web

# Build with additional PyInstaller flags
python -m eel my_app.py frontend --onefile --noconsole

# Exclude specific modules
python -m eel app.py web --exclude-module win32com --exclude-module numpy

# Build with custom name and icon
python -m eel main.py static --name "My App" --icon app.ico

# One-file executable without console
python -m eel script.py web_files --onefile --noconsole --windowed

Automatic PyInstaller Configuration

The CLI automatically configures PyInstaller with required Eel-specific settings:

Hidden Import: Automatically includes bottle_websocket dependency
Data Files: Bundles eel.js file for browser communication
Web Assets: Includes entire web folder in executable
Cross-platform: Works on Windows, macOS, and Linux

Build Process Details

The CLI performs these steps automatically:

Dependency Detection: Identifies required hidden imports for Eel functionality
Asset Bundling: Packages web folder and eel.js into executable
PyInstaller Execution: Runs PyInstaller with optimized configuration
Output Generation: Creates executable in dist/ directory

Example Build Output:

$ python -m eel my_app.py web --onefile
Building executable with main script 'my_app.py' and web folder 'web'...

Running:
pyinstaller my_app.py --hidden-import bottle_websocket --add-data eel.js;eel --add-data web;web --onefile

[PyInstaller output...]

Common PyInstaller Options

Frequently used PyInstaller flags with Eel applications:

# Application options
--onefile           # Create single executable file
--onedir           # Create directory with executable and dependencies
--noconsole        # Hide console window (Windows)
--windowed         # Same as --noconsole

# Debugging options  
--debug=all        # Enable debug output
--console          # Show console for debugging

# Optimization options
--exclude-module MODULE    # Exclude unnecessary modules
--strip                   # Strip debug symbols (Linux/macOS)

# Customization options
--name NAME              # Executable name
--icon ICON             # Application icon
--version-file FILE     # Version information file (Windows)

Development Workflow

Recommended workflow for building Eel applications:

# 1. Development phase - test locally
python my_app.py

# 2. Testing phase - build directory version
python -m eel my_app.py web --onedir

# 3. Distribution phase - build single file
python -m eel my_app.py web --onefile --noconsole

# 4. Final release - with custom branding
python -m eel my_app.py web --onefile --noconsole --name "My App" --icon app.ico

Troubleshooting Common Issues

Missing Dependencies:

# Include additional hidden imports
python -m eel app.py web --hidden-import your_module

# Include data files manually
python -m eel app.py web --add-data "path/to/file;destination"

Large File Sizes:

# Exclude unnecessary modules
python -m eel app.py web --exclude-module tkinter --exclude-module matplotlib

Runtime Errors:

# Build with console for debugging
python -m eel app.py web --console

# Enable debug mode
python -m eel app.py web --debug=all

Virtual Environment Considerations

When using virtual environments, ensure PyInstaller uses the correct Python environment:

# Activate virtual environment first
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# Then build
python -m eel my_app.py web --onefile

Distribution Best Practices

File Organization

my_eel_app/
├── main.py           # Main application script
├── web/              # Web assets directory
│   ├── index.html
│   ├── style.css
│   └── script.js
├── requirements.txt  # Python dependencies
└── build.bat        # Build script

Build Script Example

#!/bin/bash
# build.sh - Automated build script

echo "Building Eel application..."

# Clean previous builds
rm -rf build/ dist/

# Build executable
python -m eel main.py web \
    --onefile \
    --noconsole \
    --name "My Eel App" \
    --icon assets/app.ico \
    --exclude-module tkinter \
    --exclude-module matplotlib

echo "Build completed. Executable in dist/ directory."

Install with Tessl CLI