xsetuper

xsetuper creates standalone executables from Python scripts, with the same performance as the original script. It is cross-platform and should work on any platform that Python runs on.

Features

• Cross-platform: Windows, macOS, Linux
• Built-in GUI — manage, configure and build projects visually; no extra dependencies (uses tkinter from the standard library)
• Fast builds with optimized module discovery
• Simple CLI: xsetuper --script myapp.py to freeze
• pyproject.toml configuration support
• GUI and console application support
• MSI, DMG, AppImage, DEB, RPM installer generation
• Automatic dependency detection

Graphical Interface

xsetuper ships with a full graphical interface — no extra packages to install:

xsetuper gui
# or
xsetuper-gui
# or open a specific project folder
xsetuper-gui /path/to/project

The GUI provides:

• Project manager — save/load projects (.xsetuper.json) and export pyproject.toml
• Recent projects list with one-click reopening
• Multiple executables per project, with icon, base (console/gui), manifest, shortcut and UAC options
• Module control — include/exclude lists, packages, build constants
• Files & zip control — extra data files, zip include/exclude packages, path replacement
• Smart setup — analyzes your script's imports and suggests include/exclude lists
• Quickstart wizard — two questions and your project is ready
• One-click build with live console output, cancel support, and post-build actions (run app / open output folder)
• Installer creation — MSI, DMG, AppImage, DEB, RPM toggles run automatically after build (per platform)
• Dark / light themes with automatic system detection

Installation

pip install xsetuper

Or with conda:

conda install -c conda-forge xsetuper

Quick Start

CLI Usage

The simplest way to freeze your Python application:

xsetuper --script myapp.py

This creates a standalone executable in build/exe.<platform>-<python-version>/.

Common CLI Options

# Specify output directory
xsetuper --script myapp.py --target-dir dist/

# Set custom executable name
xsetuper --script myapp.py --target-name MyApp

# Include an icon
xsetuper --script myapp.py --icon icon.ico

# GUI application (no console window on Windows)
xsetuper --script myapp.py --base gui

# Build with optimization
xsetuper build_exe --optimize=2

pyproject.toml Configuration

Add your freeze configuration directly in pyproject.toml:

[tool.xsetuper.build_exe]
excludes = ["tkinter", "unittest"]
includes = ["my_package"]
optimize = 1
silent = false

[[tool.xsetuper.executables]]
script = "myapp.py"
base = "gui"
target_name = "MyApp"
icon = "icon.ico"

Then build with:

xsetuper build_exe

Python API

from xsetuper import setup, Executable

setup(
    name="MyApp",
    version="1.0",
    description="My Application",
    executables=[
        Executable(
            "myapp.py",
            base="gui",
            target_name="MyApp",
            icon="icon.ico",
        )
    ],
)

Creating Installers

Windows (MSI)

xsetuper bdist_msi

macOS (DMG)

xsetuper bdist_dmg

Linux (AppImage)

xsetuper bdist_appimage

Linux (DEB)

xsetuper bdist_deb

Advanced Usage

Excluding Modules

[tool.xsetuper.build_exe]
excludes = [
    "tkinter",
    "unittest",
    "email",
    "xml",
    "pydoc",
]

Including Data Files

[tool.xsetuper.build_exe]
include_files = [
    ("data/", "data/"),
    ("config.json", "config.json"),
]

Optimizing the Build

[tool.xsetuper.build_exe]
optimize = 2  # Maximum optimization (removes docstrings)
no_compress = false
zip_include_packages = ["encodings"]

Development

git clone https://github.com/ifekri/xsetuper.git
cd xsetuper
pip install -e ".[dev]"

Running Tests

pytest tests/ -v

Coverage

pytest tests/ --cov=xsetuper --cov-report=term-missing

License

MIT License. See LICENSE for details.