idfmgr

README

idfmgr

Simplifying ESP32 project management

Project Description

idfmgr is a command-line wrapper around Espressif's idf.py tool that simplifies ESP32 development workflows. It handles the complexity of managing multiple ESP-IDF versions, provides project templates, and makes it easy to switch between GCC and Clang toolchains—all while leveraging the power of the official idf.py tool underneath.

Key Features

• Version Management: Install, list, and remove multiple ESP-IDF versions
• Project Templates: Create projects with base, Arduino or IDF component templates
• Dual Toolchain Support: Build with GCC or Clang (separate build directories)
• Per-Project Versioning: Track ESP-IDF version with .espidf-version files
• Integrated Workflow: Build and flash with automatic environment setup
• Multi-Target Support: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2

Table of Contents

• idfmgr - Simplifying ESP32 project management
  • Project Description
    • Key Features
• Table of Contents
  • Installation
    • Using go install (Recommended)
    • Download Pre-built Binaries
    • Build from Source
    • Prerequisites
  • Quick Start
  • Commands
    • Version Management
      • list
      • install <version>
      • installed
      • remove [version...]
    • Project Management
      • create <project-name>
      • activate
      • info
    • Building and Flashing
      • build
      • flash
      • exec [idf.py args...]
  • Templates
    • Base Template
    • Arduino Template (--arduino)
    • IDF Component Template (--component)
  • Configuration
    • Environment Variables
    • Per-Project Configuration
  • Tips & Tricks
    • Dual Toolchain Workflow
    • Quick Arduino Development
    • Using idf.py Directly
  • ESP IDF Project Structure
  • License

Installation

Using go install (Recommended)

If you have Go installed (1.21+), this is the easiest method:

go install github.com/Dwarf1er/idfmgr@latest

Make sure $GOPATH/bin (typically ~/go/bin) is in your PATH.

Download Pre-built Binaries

Download the latest release for your platform from the releases page, replace version as needed in the commands:

Linux:

wget https://github.com/Dwarf1er/idfmgr/releases/download/vX.X.X/idfmgr-linux-x64-vX.X.X
chmod +x idfmgr-linux-x64-vX.X.X
sudo mv idfmgr-linux-x64-vX.X.X /usr/local/bin/idfmgr

macOS:

# Intel Mac
wget https://github.com/Dwarf1er/idfmgr/releases/download/vX.X.X/idfmgr-osx-x64-vX.X.X
chmod +x idfmgr-osx-x64-vX.X.X
sudo mv idfmgr-osx-x64-vX.X.X /usr/local/bin/idfmgr

# Apple Silicon Mac
wget https://github.com/Dwarf1er/idfmgr/releases/download/vX.X.X/idfmgr-osx-arm64-vX.X.X
chmod +x idfmgr-osx-arm64-vX.X.X
sudo mv idfmgr-osx-arm64-vX.X.X /usr/local/bin/idfmgr

Windows: Download the .exe file and add it to your PATH.

Build from Source

git clone https://github.com/Dwarf1er/idfmgr.git
cd idfmgr
go build -o idfmgr
sudo mv idfmgr /usr/local/bin/
# or move to a directory in your PATH on Windows

Prerequisites

idfmgr will check for these automatically, but you'll need:

• Git
• Python 3
• CMake
• Ninja build system
• wget

Quick Start

# 1. Install an ESP-IDF version
idfmgr install v5.1.2

# 2. Create a new project
idfmgr create my-project

# 3. Build with GCC (default)
cd my-project
idfmgr build

# 4. Flash to device
idfmgr flash --monitor

Commands

Version Management

list

List available ESP-IDF versions from GitHub releases

idfmgr list

install <version>

Install a specific ESP-IDF version

# Install specific version
idfmgr install v5.1.2

# Install latest version
idfmgr install latest

# Skip prerequisite checks
idfmgr install v5.1.2 --skip-prereqs

# Skip Clang toolchain installation
idfmgr install v5.1.2 --skip-clang

installed

List currently installed ESP-IDF versions

idfmgr installed

remove [version...]

Remove installed ESP-IDF versions

# Remove specific version
idfmgr remove v5.1.2

# Remove multiple versions
idfmgr remove v4.4.6 v5.0.0

# Remove all versions
idfmgr remove all

# Skip confirmation prompt
idfmgr remove v5.1.2 --force

Project Management

create <project-name>

Create a new ESP-IDF project

# Basic project
idfmgr create my-project

# Arduino-based project
idfmgr create my-arduino-project --arduino

# Specific ESP-IDF version
idfmgr create my-project --version v5.1.2

# Specific target chip
idfmgr create my-project --target esp32s3

# Combined options
idfmgr create my-project --arduino --target esp32s3 --version v5.1.2

What gets created:

• .espidf-version - Tracks ESP-IDF version for this project
• .clangd - LSP configuration for IDE support
• sdkconfig.defaults - Sensible default configurations
• .gitignore - Ignores build artifacts and generated files
• Git repository with initial commit

activate

Set up the ESP-IDF environment for the current project automatically. This reads the .espidf-version file and outputs shell commands to configure environment variables.

Linux/MacOS

# Activate environment in the current shell
eval "$(idfmgr activate)"

Windows (PowerShell)

# Launch a PowerShell with ESP-IDF environment configured
idfmgr activate

What it does:

• Sets IDF_PATH, PATH, IDF_PYTHON_ENV_PATH, and other ESP-IDF variables (including esp-clang for LSP integration in your IDE)
• Works for the project’s specific ESP-IDF version
• Enables subsequent idf.py or idfmgr exec commands without manual export

info

Show project and environment information

idfmgr info

Output includes:

• Current ESP-IDF version
• Installation path
• Build status (GCC/Clang)
• Manual activation instructions
• Usage examples

Building and Flashing

build

Build the current project

# Build with GCC (default) - output: build/
idfmgr build

# Build with Clang - output: build-clang/
idfmgr build --clang

flash

Flash the built project to device

# Flash GCC build
idfmgr flash

# Flash Clang build
idfmgr flash --clang

# Flash and open serial monitor
idfmgr flash --monitor
idfmgr flash -m

# Specify serial port
idfmgr flash --port /dev/ttyUSB0
idfmgr flash -p /dev/ttyUSB0

# Combined options
idfmgr flash --clang --monitor --port /dev/ttyUSB1

exec [idf.py args...]

Execute any idf.py command with proper environment setup

# Open menuconfig
idfmgr exec menuconfig

# Monitor serial output
idfmgr exec monitor

# Monitor with specific port
idfmgr exec -p /dev/ttyUSB0 monitor

# Erase flash
idfmgr exec erase-flash

# Full clean
idfmgr exec fullclean

# App-only flash (faster)
idfmgr exec app-flash

This command is perfect for accessing idf.py features not wrapped by idfmgr, while still benefiting from automatic environment management.

Templates

Base Template

Standard ESP-IDF project with:

• Renamed main.c for consistency
• Pre-configured .clangd for LSP support
• Sensible defaults in sdkconfig.defaults
• Git repository initialized

Arduino Template (--arduino)

All base template features plus:

• Arduino-ESP32 as git submodule
• Pre-configured CMake for Arduino support
• main.cpp with Arduino-style setup() and loop()
• Serial communication ready

IDF Component Template (--component)

Minimal ESP-IDF registry component with:

• Standard component folder structure (include/ and src/)
• .gitignore to ignore build artifacts and temporary files
• Git repository initialized for version control
• Ready to be added to any ESP-IDF project or published to the ESP-IDF registry

---

Configuration

Environment Variables

• ESP_BASE - Installation directory for ESP-IDF versions (default: ~/.esp)

export ESP_BASE=/custom/path/to/esp

Per-Project Configuration

Each project contains a .espidf-version file:

v5.1.2

This ensures consistent ESP-IDF version across builds and between developers.

---

Tips & Tricks

Dual Toolchain Workflow

Build and flash with both toolchains:

idfmgr build          # GCC -> build/
idfmgr build --clang  # Clang -> build-clang/

idfmgr flash          # Flash GCC build
idfmgr flash --clang  # Flash Clang build

Quick Arduino Development

idfmgr create blink --arduino --target esp32s3
cd blink
idfmgr build --clang
idfmgr flash --clang --monitor

Using idf.py Directly

When you need features not wrapped by idfmgr, use exec:

# Instead of manually sourcing export.sh and running idf.py
idfmgr exec menuconfig

# Instead of:
# . ~/esp/esp-idf-v5.1.2/export.sh
# idf.py menuconfig

Or check the manual activation path:

idfmgr info
# Shows: . ~/esp/esp-idf-v5.1.2/export.sh

ESP IDF Project Structure

my-project/
├── .espidf-version          # ESP-IDF version tracking
├── .clangd                  # LSP configuration
├── .gitignore               # Build artifacts ignored
├── sdkconfig.defaults       # Default configurations
├── CMakeLists.txt           # Root CMake configuration
├── main/
│   ├── CMakeLists.txt       # Main component configuration
│   └── main.c (or main.cpp) # Application entry point
└── components/              # Custom components
    └── arduino/             # (Arduino template only)

License

This software is licensed under the MIT license