手动安装 ESPHome
WARNING
Python 3.14 尚不支持。 请使用 Python 3.11、3.12 或 3.13。 Python 3.14 引入了破坏性更改，ESPHome 的依赖项尚未适应。
Windows
Section titled “Windows”从官方网站下载 Python。使用 Python 3.11、3.12 或 3.13。
确保勾选 “Add Python to PATH”，并完成整个安装程序。
注销并重新登录，或重启计算机。选择最方便的方式。
打开开始菜单并输入 cmd。按回车键。
在出现的终端中，检查 Python 是否已安装：
python --version应该显示类似：
Python 3.11.13看起来没问题？您可以继续安装 ESPHome：
pip3 install wheelpip3 install esphome您应该可以开始了！您可以通过以下命令测试是否正确安装：
esphome version应该显示类似：
Version: 2025.8.0NOTE
您可能还需要安装 git 以使用外部组件功能。 从官方链接下载 git
ESPHome 支持 macOS。在 macOS 上安装 ESPHome 有几种方式：
- Homebrew
- pip
- 克隆存储库
Homebrew
Section titled “Homebrew”通过 Homebrew 安装的一种简单方式：
brew install esphome验证安装：
esphome version应该显示类似：
Version: 2025.8.0NOTE
-
如果您在 Homebrew 安装过程中遇到任何问题，请查看 ESPHome Homebrew Formula 页面了解更多信息。
-
Homebrew 可能不会总是立即提供最新版本。更新 Homebrew 将自动更新 ESPHome。如果这对您来说可以接受，Homebrew 是安装 ESPHome 最简单的方式。
要获取最新版本，请使用 pip 安装。这可能设置起来更困难，可能需要额外的依赖项和路径设置。强烈建议设置虚拟环境。如果您不熟悉 Python 虚拟环境，Homebrew 可能更容易。
您需要 Python 3.11 或更新版本。虽然您的 Mac 可能已安装 Python 版本，但可能不是最新的。可以从官方网站或使用 Homebrew 安装 Python。安装 Python 后，创建并激活虚拟环境，然后使用 pip 安装 ESPHome：
$ python3 -m venv venv # 最后一个参数是安装虚拟环境的文件夹$ source venv/bin/activate # 适用于 bash 或兼容的 shell。如果使用不同的 shell，使用 activate.csh 或 activate.fish(venv) $ pip install esphome # 在虚拟环境中安装 ESPHome(venv) $ esphome version每次要使用 ESPHome 时，都需要激活虚拟环境，如上所示。激活后，您将在提示符开头看到 (venv)。
出于开发目的，我们建议克隆存储库。有关设置开发环境的更多信息，请参阅我们的开发者网站。
您的发行版可能已经安装了 Python。确认它至少是 3.11 版本：
python3 --version应该显示类似：
Python 3.11.13看起来没问题？现在创建一个虚拟环境来包含 ESPHome 及其依赖项。
python3 -m venv venvsource venv/bin/activate根据您的 shell 配置，您可能会也可能不会在提示符开头看到 (venv)。这表示您处于虚拟环境中。
您可以继续安装 ESPHome：
pip3 install esphomeCAUTION
不要使用 sudo 配合 pip。如果这样做，您在更新发行版时会遇到问题。
有关详情，请参阅 DontBreakDebian。
pip install 在这种情况下等同于 make install。文章中的建议适用于所有 Linux 发行版，不仅仅是 Debian。
有些人在没有虚拟环境的情况下安装 ESPHome，这可能导致 PATH 等问题。不使用 venv 的安装被认为是”不支持”的，因为人们需要了解您的确切系统设置。
此时，您应该能够确认 ESPHome 已成功安装：
esphome version应该显示类似：
Version: 2025.8.0如果您收到类似 “Command not found” 的错误，您需要使用 export PATH=$PATH:$HOME/.local/bin 将二进制文件添加到您的 PATH。
要永久设置，您可以运行 echo 'export PATH=$PATH:$HOME/.local/bin' >> $HOME/.bashrc，然后注销并重新登录。