Getting Started¶
Before you start¶
You need:
- Home Assistant 2026.11.0 or later.
- Google speakers or displays. The integration is known to work with the original Google Home, Google Home Mini, Nest Mini, Nest Audio and Nest Hub. It doesn't add the other devices in your Google Home app, such as lights or thermostats. See Other Google Home devices.
- A Google account that is a member of your home in the Google Home app, or of each home if your devices are in several. Open the Google Home app with that account and check that your devices are listed.
- Home Assistant on the same local network as your devices, so the integration finds them automatically. If you run Home Assistant in Docker, set the container's network mode to
host, as the official installation guide does. If your devices are on another network, or the container can't usehostmode, add them as known hosts instead.
Use a separate Google account
The integration needs credentials that give full access to the Google account you sign in with. Instead of your main account, create a new Gmail account, one ending in @gmail.com, and invite it to your home in the Google Home app. If its credentials leak, only that account is exposed. See issue #124 for the discussion.
Google Workspace accounts can't be invited to a home, and some personal accounts with non-Gmail addresses have had missing devices; see No devices appear.
Install the integration¶
Google Keep Sync
If you use Google Keep Sync, update it to 1.2.0 first.
The Marketplace replaced HACS in Home Assistant 2026.11. If you installed the integration with HACS, Home Assistant moved it to the Marketplace when you updated Home Assistant, so you don't need to install it again.
The first time you open the Marketplace, it asks you to accept a notice about community content before you can search or install: select I understand the risks and agree, then Continue.
- Open Google Home in the Marketplace, or go to Settings > Marketplace, search for Google Home and open it.
- Select Install, then Install again in the dialog.
Home Assistant then opens the integration's setup: continue from step 2 of Add the integration. If the Marketplace says that Home Assistant needs a restart instead, select Restart Home Assistant, then add the integration.
Updates appear in Settings, with Home Assistant's own updates. After you install one, restart Home Assistant; a repair offers to do it for you.
- Download the source code ZIP of the latest release and unpack it.
- Find your Home Assistant configuration folder, the one that contains
configuration.yaml. If it has nocustom_componentsfolder, create one. - Copy the
custom_components/google_homefolder from the release into thatcustom_componentsfolder. - Restart Home Assistant.
To update, repeat these steps with the new release. Delete the old google_home folder first.
To see which version you have, open Settings > Devices & services > Google Home. The version is under the title.
Add the integration¶
- Add the Google Home integration, or go to Settings > Devices & services > Add integration and search for Google Home. If that page shows a Google Home card under Discovered, you can select Add on it instead.
- Choose how to sign in, and follow its steps below:
- Browser sign-in (recommended): you sign in to Google in a desktop browser and copy a cookie from it.
- Master token: if you already have one, for example from another tool.
- If your Google account is a member of several homes, choose the homes whose speakers and displays to add, and select Submit. All homes are selected at first. If Google doesn't give the integration your homes at that moment, Home Assistant skips this step and adds every home's devices. Either way, you can change this later; see Choose homes.
Home Assistant then adds a device for each Google Cast device in the homes you chose, with the entities for it. Devices that have no alarms or timers, such as an NVIDIA Shield, get fewer entities. A speaker pair is added once, as one device with the pair's name from the Google Home app.
Home Assistant shows the Google Home card under Discovered when it finds a Google Cast device on your network and the integration isn't set up. The card doesn't mean that your account or devices were found: you still sign in. If you don't want to set up the integration, select Ignore. If you delete the integration but keep it installed, the card can come back.
Keep your sign-in details secret
The cookie and the master token each give access to your Google account. Don't share them or post them in an issue.
Browser sign-in¶
You need a computer with a desktop browser, such as Chrome, Edge or Firefox. Phones don't show the cookies you need. You sign in on Google's own page, so you don't need an app password, a script or any change to 2-Step Verification.
- In a private browser window, open accounts.google.com/EmbeddedSetup and sign in with the Google account you want to use.
- Accept the prompt. The page may then keep loading forever; that is expected.
- Press
F12, orCmd+Option+Ion a Mac, to open the browser's developer tools. Then open the cookies forhttps://accounts.google.com:- Chrome or Edge: Application > Cookies. If you can't see the Application tab, select
>>to show more tabs. - Firefox: Storage > Cookies.
- Chrome or Edge: Application > Cookies. If you can't see the Application tab, select
- Find the
oauth_tokenrow, double-click its value to select all of it, and copy it. It starts withoauth2_4/. - In Home Assistant, on the Browser sign-in form, paste the cookie into oauth_token cookie and select Submit.
The cookie can expire quickly and works only once, so paste it straight away. If setup asks for a new cookie, close the private window and repeat from step 1.
Home Assistant exchanges the cookie for a master token, names the entry after the account Google reports, and keeps only the master token.
Master token¶
Select Master token, paste the token into Google account master token, and select Submit. Copy the whole token, starting with aas_et/. The integration removes surrounding whitespace and expects at least 200 characters, including aas_et/, with no spaces or line breaks inside. The integration looks up which Google account the token belongs to and names the entry after it.
If the form says the token must start with aas_et/, check that you copied the master token. The oauth_token cookie belongs on the Browser sign-in form. If the form says the token is too short, it shows the length after trimming surrounding whitespace. If browser sign-in fails because Google returned a master token in an unexpected format, get a new cookie and try again. The Home Assistant log may have more details.
Check that it works¶
Set a timer on one speaker and check that Home Assistant shows it:
- Go to Settings > Devices & services > Google Home and select one of your speakers or displays.
- On its device page, find the Timers sensor. It shows Unavailable while no timer is running; that is expected, not an error. If Timers shows a time, a timer is already running on that speaker: choose another speaker, or wait until the timer finishes.
- Ask that speaker to set a timer, for example "Hey Google, set a timer for 10 minutes". A timer belongs to the speaker that set it, so ask the one whose page you opened.
- Wait for the next update. The integration checks your devices every 15 seconds, unless you changed the update interval. Timers then shows when the timer goes off.
- Say "Hey Google, cancel the timer". After the next update, Timers shows Unavailable again.
If it doesn't work:
- If the Google Home integration shows no devices in Home Assistant, see No devices appear.
- If the speaker has only a device sensor, a reboot button, an update sensor, and disabled Wi-Fi and uptime sensors, Home Assistant hasn't reached it yet, or it has no alarms and timers. See No alarms or timers sensors.
- If Timers still shows Unavailable after the update, check that you asked the speaker whose page you opened, and that it's on and connected to your network. Then see A device stops updating.
Use it in an automation¶
When a timer finishes sends a notification to your phone when a speaker's timer finishes. Automation examples has more, such as turning on lights before an alarm.
The examples use entity IDs such as sensor.kitchen_timers. Replace them with your own: on the device page, select Timers, then the settings (gear) icon. Entity ID shows the sensor's ID. If it has the room name twice, see Room name twice in entity IDs.
Manage the integration¶
- Change the update interval, for example if a speaker often misses updates.
- Add a device that you set up in the Google Home app later.
- Add devices on another network, such as a separate VLAN.
- Choose homes whose devices to add, if your account is a member of several.
- Remove a device, and what happens when you remove one from the Google Home app.
- Sign in again if Home Assistant reports that authentication expired.
- Remove the integration, and what to do about its master token.
Try a fix before it's released¶
A fix merged into master reaches the Home Assistant Marketplace with the next release. To try it sooner, install master in place of your current version. Only master is supported, not other branches or pull requests.
While you run master, Settings > Devices & services > Google Home still shows the version number of the latest release, so if you report a problem, say that you run master.
These steps work only if you installed the integration from the Marketplace, or with HACS before Home Assistant moved it to the Marketplace. Otherwise, use the Manual steps.
- Find the entity ID of the Google Home update entity: in Settings > Devices & services > Entities, search for
update.google_home. It's usuallyupdate.google_homeorupdate.google_home_update. - Open Settings > Tools > Actions and switch to YAML mode.
-
Enter this action, with your entity ID in place of
update.google_home:action: update.install target: entity_id: update.google_home data: version: master -
Select Perform action, then restart Home Assistant.
This installs master as it is at that moment. To get newer commits, run the action again.
An update replaces master
While you run master, Home Assistant may offer the latest release as an update, in Settings or on the integration's Marketplace page. Installing it replaces master with that release, so a fix that isn't released yet is gone. Install it only when you want to go back, then restart Home Assistant. While you test, you can open the update in Settings and select Skip: this hides only that release, and Home Assistant offers the next one as usual.
To go back when Settings offers no update, or the update can't be installed, open Google Home in the Marketplace and select ⋮ > Install another version. Under Version, choose the release marked Latest, then select Update. Restart Home Assistant afterwards.
Follow the Manual steps under Install the integration, but download master as a ZIP instead of the release, and delete the old google_home folder first. To get newer commits, repeat them. To go back, repeat them with the latest release.