bat2pe 1.4.8

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. You can embed a custom icon, 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

• build → inspect → verify pipeline — generate, examine, and validate without switching tools
• %~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 — one command, generates a same-name .exe beside the script:

bat2pe build run.bat

Specify output path and icon:

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

Show console window (for interactive foreground tools):

bat2pe build run.bat --visible

Add UAC admin elevation:

bat2pe build admin.cmd --uac

Write full version metadata:

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

💡 Besides build, there are also inspect (view exe metadata) and verify (check behavioral consistency) subcommands. Run bat2pe <command> --help for full details.

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",
    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 (including inspect, verify, and other advanced usage), 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/inspect/verify flow
• 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

Current Stage & Known Limitations

Bat2PE is ready for single-script, launcher-style batch projects. The build → inspect → verify workflow is fully operational.

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.