bat2pe 1.7.3

Windows Bat/Cmd to Exe converter with Rust CLI and Python API.

Bat2PE

English README | 中文说明 | Python API

Convert .bat / .cmd scripts to standalone .exe via CLI or Python module
Fully compatible runtime behavior, custom icon & metadata, UAC elevation, passes Kaspersky and common AV scans, zero runtime dependencies

Existing solutions like Bat To Exe Converter fall short for professionals who need to integrate the conversion step into automated workflows. Bat2PE offers no GUI — instead it provides a CLI and a directly callable Python module, letting you convert batch scripts to executables in one command and fold distribution into your pipeline.

Executables generated by Bat2PE behave identically to the original batch script, preserving %~dp0 and other special variables. Bat2PE embeds a built-in default icon unless you override it with a custom .ico, and it can also set version info, company name, and other file metadata. One flag adds UAC elevation. The output passes Kaspersky (free edition) and common antivirus scans. The generated .exe runs standalone with zero extra dependencies.

Highlights

• Drag-and-drop conversion — drop a .bat / .cmd file onto Bat2PE.exe in Windows Explorer and the conversion runs instantly, no command needed
• %~dp0 semantics preserved — temp script is written beside the .exe, not in %TEMP%, minimizing broken relative paths
• Window mode — defaults to hidden (silent background); add --visible for a foreground console
• Multi-encoding support — UTF-8 · UTF-8 BOM · UTF-16 LE BOM · ANSI/GBK auto-detected
• Dual entry points — CLI for terminals and CI/CD, Python API for scripting and automation workflows
• Native Windows resource writing — icon, version number, company name, and other metadata written to PE resource sections, visible in Explorer
• UAC elevation — a single --uac or uac=True makes the generated .exe request admin privileges
• AV-friendly — generated executables pass Kaspersky Free and common antivirus scans
• Zero extra dependencies — generated .exe runs standalone, no runtime installation required

Installation

Python Users

pip install bat2pe

After installation, call from bat2pe import build directly in your Python code.

CLI Users

Download bat2pe.exe from GitHub Releases and you're ready to go.

System Requirements

Dependency	Minimum Version
OS	Windows 10 / 11 (x64)
Python (only for Python API)	3.10+
Rust (only for building from source)	1.85+

Quick Start

CLI Usage

Simplest conversion — drop run.bat onto Bat2PE.exe in Windows Explorer, or run from command line:

bat2pe run.bat

Or drag and drop — drag run.bat onto Bat2PE.exe in Windows Explorer; no command needed:

[drag run.bat onto Bat2PE.exe]  →  run.exe created beside run.bat

Specify output path and custom icon:

bat2pe run.bat --output-exe-path dist\run.exe --icon-path app.ico

Show console window (for interactive foreground tools):

bat2pe run.bat --visible

Add UAC admin elevation:

bat2pe admin.cmd --uac

Write full version metadata:

bat2pe run.bat ^
  --company "Acme Corp" ^
  --product "My Tool" ^
  --description "Launcher" ^
  --file-version 1.2.3 ^
  --product-version 1.2.3

💡 Run bat2pe --help for the full list of options.

Python Usage

Functional API (recommended for quick use)

from bat2pe import build

result = build(input_bat_path="run.bat")
print(result.output_exe_path)  # run.exe

Object-Oriented API (recommended for complex scenarios)

from bat2pe import Builder

builder = Builder(
    input_bat_path="run.bat",
    output_exe_path="dist/run.exe",
    # visible defaults to False (hidden); set True for console window
    icon_path="app.ico",  # overrides the built-in default icon
    company_name="Acme Corp",
    product_name="My Tool",
    file_version="1.2.3",
)
result = builder.build()

UAC Elevation

from bat2pe import build

result = build(
    input_bat_path="admin_task.bat",
    uac=True,
)

Error Handling

from bat2pe import build, BuildError, ERR_UNSUPPORTED_INPUT

try:
    build(input_bat_path="readme.txt")
except BuildError as e:
    if e.code == ERR_UNSUPPORTED_INPUT:
        print("Only .bat or .cmd files are supported")
    print(e.code, e.path, e.details)

For the full Python API reference, see docs/python-api.md.

How It Works

Bat2PE embeds a batch script into a native Windows PE executable. At runtime, the generated .exe:

1. Reads the embedded script content from its own PE resources
2. Writes a temporary .cmd file (with hidden attribute) in the .exe's directory
3. Executes the temp script via cmd.exe /d /c, forwarding all command-line arguments
4. Automatically deletes the temp file after execution, with orphan cleanup on abnormal termination

Why not write to %TEMP%? Because many batch scripts rely on %~dp0 to locate adjacent config files or resource directories. Placing the temp script beside the .exe preserves this semantic as much as possible, keeping behavior consistent with the original script.

Architecture Overview

┌──────────────┐    ┌──────────────┐    ┌──────────────────┐
│  CLI Users   │    │ Python Users │    │  CI/CD Pipelines │
└──────┬───────┘    └──────┬───────┘    └────────┬─────────┘
       │                   │                     │
       ▼                   ▼                     ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────────┐
│  bat2pe.exe  │    │bat2pe._native│    │  bat2pe (Python)  │
│  (Rust CLI)  │    │(PyO3 Extension)│  │   pip install     │
└──────┬───────┘    └──────┬───────┘    └────────┬─────────┘
       │                   │                     │
       └───────────────────┴─────────────────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │   bat2pe-core   │
                  │  (Rust Core Lib)│
                  └─────────────────┘

Building from Source (Developers)

If you want to build from source or contribute:

Setup

# Install dependencies
uv sync

Build All Artifacts

# Recommended (one-step build for CLI + Python extension)
uv run python scripts/compile.py

# For debug builds
uv run python scripts/compile.py --debug

Build outputs:

Artifact	Description
target/release/bat2pe.exe	Standalone CLI program
python/bat2pe/_native.pyd	Python native extension module

Manual Build

cargo build --release -p bat2pe -p bat2pe-py
uv run maturin develop

Running Tests

# Rust unit tests
cargo test --workspace

# Python integration tests (CLI, Python API, runtime behavior, etc.)
uv run pytest

Test coverage includes:

• CLI help output, argument validation, full build flow
• CLI drag-and-drop conversion
• Python API functional + object-oriented dual interfaces
• Encoding detection and unsupported encoding rejection
• Typed exception mapping
• UAC manifest writing
• Native Windows version resource writing
• Runtime %~dp0 behavior and working directory preservation
• Hidden window exit codes
• Temp file cleanup and forced termination cleanup
• Python 3.10 syntax compatibility checks

Completed Features

Item	Status
Single .bat / .cmd script conversion	✅ Fully supported
Icon & version metadata	✅ Written to native Windows PE resources
UAC admin elevation	✅ Supported
Hidden window mode	✅ Supported
Multi-encoding auto-detection	✅ UTF-8 / UTF-8 BOM / UTF-16 LE BOM / ANSI/GBK

License

This project is licensed under the MPL-2.0 license.