手动安装 ESPHome
Windows
从官方网站下载 Python。
确保勾选 “添加 Python 到 PATH”，并完成整个安装过程。
注销并重新登录，或者重启你的电脑。选择最简单的方法。
打开开始菜单并输入 cmd，然后按回车键。
在弹出的终端中，检查 Python 是否已安装：
python --version它应该显示类似以下内容：
Python 3.11.13看起来不错？你可以继续安装 ESPHome：
pip3 install wheel
pip3 install esphome然后你应该就可以使用了！你可以通过以下命令测试是否正确安装：
esphome version它应该显示类似以下内容：
Version: 2025.8.0ℹ️ Note
你可能还需要安装 git 以使用外部组件功能。从官方链接下载 git。
Mac
ESPHome 支持 macOS。在 macOS 上安装 ESPHome 有几种方法：
- Homebrew
- pip
- 克隆仓库
Homebrew
一个简单的安装方法是使用 Homebrew：
brew install esphome验证安装：
esphome version它应该显示类似以下内容：
Version: 2025.8.0ℹ️ Note
如果你遇到 Homebrew 安装问题，请查看 ESPHome Homebrew Formula 页面以获取更多信息。
Homebrew 可能不会立即提供最新版本。更新 Homebrew 会自动更新 ESPHome。如果你可以接受这一点，Homebrew 是安装 ESPHome 最简单的方法。
pip
要获取最新版本，请使用 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)。
克隆仓库
为了开发目的，我们建议克隆仓库。有关设置开发环境的更多信息，请查看我们的开发者网站。
Linux
你的发行版可能已经安装了 Python。确认其版本至少为 3.11：
python3 --version它应该显示类似以下内容：
Python 3.11.13看起来不错？现在创建一个虚拟环境来包含 ESPHome 及其依赖项。
python3 -m venv venv
source venv/bin/activate根据你的 shell 配置，你可能会或可能不会在提示符的开头看到 (venv)。这表示你处于虚拟环境中。
你可以继续安装 ESPHome：
pip3 install esphome❗ Caution
不要在 pip 中使用
sudo。如果你这样做，将来更新你的发行版时会遇到问题。详细信息，请参阅 DontBreakDebian。
pip install在此上下文中等同于make install。文章中的建议适用于所有 Linux 发行版，而不仅仅是 Debian。有些人不使用虚拟环境安装 ESPHome，这可能导致 PATH 等问题。 没有
venv的安装被认为是不“受支持的”，因为人们最终需要了解你的确切系统设置。
此时，你应该能够确认 ESPHome 已成功安装：
esphome version它应该显示类似以下内容：
Version: 2025.8.0如果你遇到“命令未找到”的错误，需要使用 export PATH=$PATH:$HOME/.local/bin 将二进制文件添加到你的 PATH。
要永久设置，你可以运行 echo 'export PATH=$PATH:$HOME/.local/bin' >> $HOME/.bashrc，然后注销并重新登录。
