Offline Archive Builder

The ESP-IDF Installation Manager provides a command-line tool called offline-installer-builder that allows you to create custom offline installation archives for specific or all ESP-IDF versions. These archives contain everything needed for offline installation — ESP-IDF source, tools, Python wheels, and prerequisites — making them ideal for air-gapped environments, enterprise deployment, or CI/CD pipelines.

Getting the Tool

You can download the offline-installer-builder from:

GitHub Releases: The tool is included as an asset in the latest release of the ESP-IDF Installation Manager. Look for offline_installer_builder-<platform>-*.zip (e.g., offline_installer_builder-windows-x64-*.zip).

Prerequisites

Before using the offline-installer-builder, ensure the following is installed:

uv: A fast Python package and project manager. The builder uses uv to install Python and manage virtual environments.
- Install from: https://github.com/astral-sh/uv
- Verify with: uv --version

💡 The builder does not bundle uv — you must install it separately.

Usage

After downloading and extracting the builder, run it from your terminal. On Linux/macOS, make it executable first:

chmod +x ./offline_installer_builder

On Windows, use offline_installer_builder.exe.

Creating an Offline Archive

1. Build Archive for a Specific IDF Version

./offline_installer_builder -c default --idf-version-override v5.1.2

This creates a single .zst archive for version v5.1.2, named like: archive_v5.1.2_<platform>.zst (e.g., archive_v5.1.2_linux-x64.zst)

2. Build Archives for All Supported IDF Versions

./offline_installer_builder -c default --build-all-versions

This builds one .zst archive per supported IDF version, each named with its version and platform.

✅ Use this for full offline mirror creation.

3. Build Using a Custom Configuration File

./offline_installer_builder -c /path/to/your/config.toml

Your config.toml can specify which versions and targets to include. Example:

# config.toml
idf_versions = ["v5.0.4", "v5.1.2"]
target = ["esp32", "esp32s3", "esp32c3"]
mirror = "https://github.com"
tools_json_file = "tools/tools.json"

⚠️ When using --build-all-versions or --idf-version-override, the idf_versions field in your config is ignored.

Command-Line Options

Short	Long	Description
`-c`	`--create-from-config <CONFIG>`	Create archive from TOML config. Use `"default"` for defaults.
`-a`	`--archive <FILE>`	Extract a `.zst` archive for inspection.
`-p`	`--python-version <VERSION>`	Python version to bundle (default: `3.11`).
`--wheel-python-versions <V1,V2,...>`	Comma-separated Python versions for which to download wheels (e.g., `3.10,3.11,3.12`). Defaults to all supported on POSIX, single version on Windows.
`--idf-version-override <VERSION>`	Build archive for only this IDF version (e.g., `v5.1.2`).
`--build-all-versions`	Build separate archives for all supported IDF versions.
`-v`	`--verbose`	Increase log verbosity (use `-vv` or `-vvv` for more detail).

Inspecting an Archive

To examine the contents of a .zst archive:

./offline_installer_builder --archive archive_v5.1.2_linux-x64.zst

This extracts the archive into a directory named archive_v5.1.2_linux-x64.zst_extracted/.

Useful for debugging or verifying contents.

Output

The builder generates .zst archives in the current working directory. Each archive is self-contained and can be used with:

eim install --use-local-archive archive_v5.1.2_linux-x64.zst

📁 Archive structure (when extracted):

├── esp-idf/           # ESP-IDF source
├── dist/              # Downloaded tools (xtensa-esp-elf, etc.)
├── python_env_*/      # Python virtual environments
├── wheels_py*/        # Pre-downloaded Python wheels
├── scoop/             # (Windows only) Offline Scoop prerequisites
└── config.toml        # Configuration used to build this archive

Advanced Usage

Building for CI/CD or Release Automation

You can integrate the builder into GitHub Actions or other CI systems. Example workflow:

- name: Build all versions
  run: |
    ./offline_installer_builder -c default --build-all-versions
    mkdir -p artifacts
    mv archive_v* artifacts/

Each platform (Linux, Windows, macOS) must run the builder separately — archives are platform-specific.

Python Wheel Compatibility

By default, the builder downloads wheels for multiple Python versions to maximize compatibility. You can override this:

./offline_installer_builder -c default --idf-version-override v5.1.2 --wheel-python-versions 3.11,3.12

This ensures the archive includes wheels compatible with Python 3.11 and 3.12.

Troubleshooting

“UV not found”: Install uv first. See https://github.com/astral-sh/uv
No archives generated: Check logs (offline_installer.log). Ensure network connectivity and disk space.
Checksum failures: Retry or check mirror URLs in config.
Windows prerequisites fail: Ensure you’re running in an environment with internet access during build.