# 在 Linux 上安装 ESP-IDF 及工具链

[English]

本章节将介绍如何使用 ESP-IDF 安装管理器 (EIM) 在 Linux 发行版（例如 Ubuntu）上安装 ESP-IDF 及其所需工具。

备注

本章节描述了 ESP-IDF v6.0 及以上版本的默认和推荐安装方式。如使用 ESP-IDF v6.0 之前版本的默认安装方式，请参考 Linux 上的传统安装方法。

## 第一步：安装依赖包（可选）

如计划通过 APT 安装 EIM，可跳过本步骤。

如使用其他方式安装 EIM，请根据 Linux 发行版安装相应的 依赖包。

备注

ESP-IDF 要求 Python 版本至少为 3.10。

EIM 所需的 Python 版本，请参考 EIM 文档。

## 第二步：安装 EIM

您可以使用以下任一方法安装 EIM：

- 下载 EIM

- 通过 APT 安装（Debian 发行版）

- 通过 DNF 安装（RPM 发行版）

- 通过 Homebrew 安装

通过 APT 或 DNF 安装 EIM 便于后续升级更新。

### 下载 EIM

可选择下载在线或离线安装程序的图形用户界面 (GUI) 或命令行界面 (CLI) 版本。

### 通过 APT 安装（Debian 发行版）

将 EIM 仓库添加到 APT 源列表，以便后续使用 APT 安装 EIM：

    echo "deb [trusted=yes] https://dl.espressif.com/dl/eim/apt/ stable main" | sudo tee /etc/apt/sources.list.d/espressif.list

    sudo apt update

然后，通过 APT 安装 EIM 的命令行界面 (CLI) 和图形用户界面 (GUI)，或仅安装命令行界面 (CLI)：

- GUI 和 CLI：

        sudo apt install eim

- 仅 CLI：

        sudo apt install eim-cli

### 通过 DNF 安装（RPM 发行版）

将 EIM 仓库添加到 DNF 源列表，以便后续使用 DNF 安装 EIM：

    sudo tee /etc/yum.repos.d/espressif-eim.repo << 'EOF'
    [eim]
    name=ESP-IDF Installation Manager
    baseurl=https://dl.espressif.com/dl/eim/rpm/$basearch
    enabled=1
    gpgcheck=0
    EOF

然后，通过 DNF 安装 EIM 的命令行界面 (CLI) 和图形用户界面 (GUI)，或仅安装命令行界面 (CLI)：

- GUI 和 CLI：

        sudo dnf install eim

- 仅 CLI：

        sudo dnf install eim-cli

### 通过 Homebrew 安装

也可以使用 Homebrew 在 Linux 上安装 EIM，此方法适用于大多数 Linux 发行版。如果不想使用系统包管理器，Homebrew 也是一个不错的选择。

首先，如果尚未安装 Homebrew，请先安装：

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

然后添加 Espressif tap 并安装 EIM：

    # 添加 Espressif tap
    brew tap espressif/eim

    # 仅安装 CLI
    brew install eim

    # 或安装 GUI（含 CLI）
    brew install --cask eim-gui

后续更新 EIM：

    brew upgrade eim
    # 或
    brew upgrade --cask eim-gui

备注

GUI 版本需要图形环境，不同的 Linux 发行版可能有不同的额外依赖。

## 第三步：使用 EIM 安装 ESP-IDF

您可以使用以下任一方法安装 ESP-IDF 及其所需工具，具体取决于您的需求：

- 使用 EIM GUI 在线安装

  适合大多数用户。通过图形用户界面安装 ESP-IDF 及其所需工具，需要网络连接。

- 使用 EIM CLI 在线安装

  通过命令行安装 ESP-IDF 及其所需工具，需要网络连接。

- 使用已有配置文件在线安装

  使用从其他电脑复制的配置文件安装 ESP-IDF 及其所需工具，适用于 GUI 和 CLI，但需要网络连接。

- 离线安装

  从本地包安装 ESP-IDF 及其所需工具，无需网络连接。

### 使用 EIM GUI 在线安装

打开 ESP-IDF 安装管理器应用程序 eim。

之后，在 `新安装` 下点击 `开始安装`。

EIM 开始安装

备注

如果之前未安装过 ESP-IDF，GUI 中不会显示 `管理安装`，仅显示 `新安装` 选项。

在 `简易安装` 下，点击 `开始简易安装`，使用默认设置安装最新稳定版本的 ESP-IDF。

EIM 简易安装

如果所有先决条件和路径检查都通过，将看到 `准备安装` 页面。点击 `开始安装` 以开始安装。

EIM 准备安装

安装过程中，可以直接在界面中查看安装进度。

EIM 安装中

安装完成后，会出现 `安装完成` 页面。

EIM 安装完成

如果安装失败，可以：

- 点击界面底部的 `日志` 查看错误详情。解决问题后，点击 `重试` 重新开始安装。

- 或者，使用 自定义安装。

备注

- 如需选择 ESP-IDF 版本或自定义安装路径，请使用 `自定义安装`。更多说明请参阅 EIM 文档 > Expert Installations。

- 如需管理现有安装，请参阅 EIM 文档 > Version Management。

### 使用 EIM CLI 在线安装

运行以下命令，在非交互模式下使用默认设置安装最新稳定版本的 ESP-IDF：

    eim install

如果运行上述命令时遇到问题，或者需要自定义安装路径、选择 ESP-IDF 版本或修改其他设置项，请启动交互式安装向导，并按照屏幕上的提示操作：

    eim wizard

如果安装向导中没有想要安装的 ESP-IDF 版本，请运行以下命令来安装任意可选 版本。例如，要安装 ESP-IDF v5.4.2，请运行：

    eim install -i v5.4.2

安装完成后，会在终端中看到以下消息：

    2025-11-03T15:54:12.537993300+08:00 - INFO - Wizard result: %{r}
    2025-11-03T15:54:12.544174+08:00 - INFO - Successfully installed IDF
    2025-11-03T15:54:12.545913900+08:00 - INFO - Now you can start using IDF tools

备注

- 要查看所有可用选项，请运行：

        eim --help

- 有关 CLI 使用的更多信息，请参阅：

  - EIM 文档 > CLI Configuration

  - EIM 文档 > CLI Commands

### 使用已有配置文件在线安装

安装 ESP-IDF 时，安装程序会自动将设置保存到安装目录下的 `eim_config.toml` 配置文件中。此配置文件可在其他电脑上重复使用，快速复现相同的安装环境。

如需使用现有 `eim_config.toml` 文件安装 ESP-IDF，请参阅 EIM 文档 > Configuration Files。

### 离线安装

EIM 的图形用户界面和命令行界面均支持离线安装。具体操作请参阅 EIM 文档 > Offline Installation。

## 后续步骤

至此，您已准备就绪，可以使用 ESP-IDF 开发 ESP-IDF 应用程序了。接下来，请继续阅读 构建首个项目 章节，学习如何构建和运行您的第一个应用程序。

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。