macOS

安装 Home Assistant 操作系统

下载合适的镜像

• VirtualBox (.vdi)

下载后，解压镜像。如果镜像是 ZIP 文件，请解压缩。

如果您已经运行了受支持的虚拟机管理程序，请按照本指南操作。如果您不熟悉虚拟机，请直接在 Home Assistant Yellow、Raspberry Pi 或 ODROID 上安装 Home Assistant OS。

• 如果 VirtualBox 不支持您的 Mac，并且您有使用虚拟机的经验，您可以尝试在 UTM 上运行 Home Assistant Operating System。

创建虚拟机

将设备镜像加载到您的虚拟机管理程序中。（注意：您可以自由分配任意数量的资源给虚拟机，请根据您的附加需求分配足够的资源）。

最低推荐配置：

• 2 GB 内存
• 32 GB 存储
• 2vCPU

如果您的使用需要更多资源，所有这些都可以扩展。

虚拟机管理程序特定配置

VBoxManage storageattach <VM 名称> --storagectl "SATA" --port 0 --device 0 --nonrotational on --discard on

启动您的虚拟机

1. 启动虚拟机。
2. 观察 Home Assistant 操作系统的启动过程。
3. 完成后，您将能够在 homeassistant.local:8123 访问 Home Assistant。如果您运行的是较旧的 Windows 版本或具有更严格的网络配置，您可能需要通过 homeassistant:8123 或 http://X.X.X.X:8123（将 X.X.X.X 替换为您的虚拟机的 IP 地址）访问 Home Assistant。

安装并可以访问 Home Assistant 操作系统后，您可以继续完成入门设置。

安装 Home Assistant Core

先决条件

本指南假设您已经设置好操作系统并安装了 Python 3.13（包括 python3-dev 包）或更新版本。

安装依赖项

在开始之前，请确保您的系统已完全更新，本指南中的所有软件包都使用 apt 安装，如果您的操作系统没有 apt，请寻找替代方案。

sudo apt-get update
sudo apt-get upgrade -y

安装依赖:

sudo apt-get install -y python3 python3-dev python3-venv python3-pip bluez libffi-dev libssl-dev libjpeg-dev zlib1g-dev autoconf build-essential libopenjp2-7 libtiff6 libturbojpeg0-dev tzdata ffmpeg liblapack3 liblapack-dev libatlas-base-dev

上述列出的依赖项可能会有所不同或缺失，具体取决于您的系统或个人使用 Home Assistant 的情况。

创建账户

为 Home Assistant Core 添加一个名为 homeassistant 的账户。 由于此账户仅用于运行 Home Assistant Core，因此添加了额外的参数 -rm 来创建一个系统账户并创建主目录。

sudo useradd -rm homeassistant

创建虚拟环境

首先，我们将为 Home Assistant Core 的安装创建一个目录，并将所有者更改为 homeassistant 账户。

sudo mkdir /srv/homeassistant
sudo chown homeassistant:homeassistant /srv/homeassistant

接下来是为 Home Assistant Core 创建并切换到虚拟环境。这将使用 homeassistant 账户来完成。

sudo -u homeassistant -H -s
cd /srv/homeassistant
python3 -m venv .
source bin/activate

激活虚拟环境后（注意提示符会变为 (homeassistant) homeassistant@raspberrypi:/srv/homeassistant $），您需要运行以下命令来安装所需的 Python 包。

python3 -m pip install wheel

安装完所需的 Python 包后，现在可以安装 Home Assistant Core 了！

pip3 install homeassistant==2025.3.4

故障排除：如果您在环境中没有看到上述版本的 Home Assistant 包，请确保您已安装正确的 Python 版本，如先决条件中所述。

首次启动 Home Assistant Core。这将为您完成安装，自动在 /home/homeassistant 目录中创建 .homeassistant 配置目录，并安装任何基本依赖项。

hass

您现在可以通过 Web 界面访问您的安装，地址为 http://homeassistant.local:8123。

如果此地址无法访问，您也可以尝试 http://localhost:8123 或 http://X.X.X.X:8123（将 X.X.X.X 替换为您机器的 IP 地址）。