xianii/esp-idf-slim repository overview

⁠esp-idf-docker-slim

A slim version of the official ESP-IDF Docker development environment, approximately 30% smaller than the official image.

• Docker Hub image: xianii/esp-idf-slim
• IDF version source: ARG IDF_VERSION in Dockerfile (currently v5.5.3)

⁠1. Quick Start (from Docker Hub)

docker compose pull
docker compose run --rm esp-dev bash

Inside the container, you can run:

idf.py --version
idf.py build

⁠2. Unified VS Code Dev Container Setup

⁠2.1 Create the config file

Create this file in your project: .devcontainer/devcontainer.json

Example:

{
  "name": "ESP-IDF v5.5.3 (slim)",
  "dockerComposeFile": ["../docker-compose.yml"],
  "service": "esp-dev",
  "workspaceFolder": "/workspace",
  "postCreateCommand": "bash -lc 'idf.py --version && python3 --version'",
  "shutdownAction": "stopCompose",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-vscode.cpptools",
        "ms-vscode.cmake-tools",
        "ms-python.python",
        "ms-vscode.makefile-tools"
      ]
    }
  },
  "remoteUser": "root"
}

⁠2.2 Where should docker-compose.yml be placed?

• By default, this assumes docker-compose.yml is in the project root.
• Since devcontainer.json is under .devcontainer/, use ../docker-compose.yml.

⁠2.3 Which directory is mapped by default? How to change it?

Current default in docker-compose.yml:

- ./:/workspace

Meaning: the directory where docker-compose.yml is located (usually project root) is mounted to /workspace in container.

If you want to mount a different project directory:

- /absolute/path/to/your_project:/workspace

⁠2.4 Is /dev mapping required?

• Build only: you can remove - /dev:/dev.
• Flashing / serial debugging: keep it.

⁠3. Local Build

If you want to build and test the Docker locally:

docker build -t esp-idf-slim:local .
docker run --rm -it -v /absolute/path/to/your_project:/workspace esp-idf-slim:local bash