Quick Navigation
Overview Tool Comparison PyInstaller auto-py-to-exe cx_Freeze Nuitka Troubleshooting

Python to Executable

Complete guide for converting Python scripts to standalone executables

Quick Start

TL;DR: For most users, PyInstaller is the easiest option:
pip install pyinstaller
pyinstaller --onefile your_script.py

Why Convert Python to Executable?

Easy Distribution

Share your app without requiring Python installation

Source Protection

Protect your code from easy reverse engineering

System Integration

Easy integration with schedulers and automation

Tool Comparison

Easy
PyInstaller

Most popular, works out-of-the-box

  • Great compatibility
  • Easy to use
  • Larger files
Easy
auto-py-to-exe

GUI wrapper for PyInstaller

  • Visual interface
  • Beginner friendly
  • Same limitations as PyInstaller
Medium
cx_Freeze

Fast startup, native installers

  • Faster startup
  • Native installers
  • More setup required
Hard
Nuitka

True compilation, best performance

  • Fastest execution
  • Better security
  • Complex setup
Metric PyInstaller cx_Freeze Nuitka
Build Time ⚡ Fast 🐌 Slower 🐌🐌 Slowest
Startup Time 🐌 Slow ⚡ Fast ⚡⚡ Fastest
File Size 📦 Small 📦📦 Larger 📦📦📦 Largest
Security 🔒 Low 🔒 Low 🔒🔒🔒 High

Conversion Methods

Method 1: PyInstaller (Recommended)

🛠️ Setup Process

# Create virtual environment
python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install pyinstaller

🚀 Basic Usage

Simple Conversion
pyinstaller your_script.py
Single File
pyinstaller --onefile your_script.py
GUI Application
pyinstaller --onefile --windowed your_script.py
With Custom Icon
pyinstaller --onefile --icon=app.ico your_script.py

Method 2: auto-py-to-exe (GUI)

Perfect for beginners! This provides a visual interface for PyInstaller.

🛠️ Installation & Usage

pip install auto-py-to-exe
auto-py-to-exe

📝 Configuration Steps

  1. Script Location: Browse and select your .py file
  2. Onefile: Choose "One File" for single executable
  3. Console Window: Select "Window Based" for GUI apps
  4. Icon: Optional - add a custom .ico file
  5. Additional Files: Add any data files your script needs
  6. Convert: Click "CONVERT .PY TO .EXE"

Method 3: cx_Freeze (Fast Startup)

🛠️ Installation

pip install cx_freeze

📝 Setup Script (setup.py)

from cx_Freeze import setup, Executable

build_options = {
'packages': [],
'excludes': [],
'include_files': []
}

executables = [
Executable('your_script.py', base='Win32GUI')
]

setup(
name='YourApp',
version='1.0',
options={'build_exe': build_options},
executables=executables
)

🚀 Build Commands

# Build executable
python setup.py build

# Create Windows installer
python setup.py bdist_msi

Method 4: Nuitka (Performance)

Advanced users only! Requires C compiler installation.

🛠️ Prerequisites & Installation

# Windows: Install MinGW64 or Visual Studio
# macOS: Install Xcode command line tools
# Linux: Install GCC

pip install nuitka

🚀 Basic Usage

# Compile to executable
python -m nuitka --onefile your_script.py

# GUI application
python -m nuitka --onefile --windows-disable-console your_script.py

# With optimizations
python -m nuitka --onefile --enable-plugin=anti-bloat your_script.py

Troubleshooting

🔧 Common Issues & Solutions

ImportError: Module not found

# Add hidden imports
pyinstaller --hidden-import=module_name your_script.py

Missing Data Files

# Include data files
pyinstaller --add-data "data_folder;data_folder" your_script.py

# Use this in your Python code:
import sys
import os

def resource_path(relative_path):
if hasattr(sys, '_MEIPASS'):
return os.path.join(sys._MEIPASS, relative_path)
return os.path.join(os.path.abspath("."), relative_path)

Large File Sizes

Tips to reduce executable size:
  • Use virtual environments (most important!)
  • Exclude unnecessary modules with --exclude-module
  • Use UPX compression
  • Consider using --onedir instead of --onefile

Antivirus False Positives

Solutions:
  • Add exclusions to your antivirus
  • Use code signing certificates
  • Consider Nuitka for better reputation
  • Submit to antivirus vendors for whitelisting

🐛 Debugging Tips

  1. Test in --onedir mode first for easier debugging
  2. Run executable from command line to see error messages
  3. Use --log-level=DEBUG for verbose output
  4. Check build/warn-*.txt files for warnings
Additional Resources
Acknowledgments
  • PyInstaller Team
  • cx_Freeze Developers
  • Nuitka Project
  • auto-py-to-exe

Licensed under MIT License | Contribute on GitHub | Star this guide if it helped you!