A detailed tutorial for integrating Gree air conditioners in Home Assistant 2025.12.2.
This tutorial prioritizes Home Assistant’s official built-in integration, which is the most stable and beginner-friendly solution and requires no third-party add-ons.
Core prerequisites (must read)
Before you start, be sure to complete the following preparation, otherwise the device cannot be integrated:
- Device already on the network: your Gree air conditioner must already be connected to your home Wi-Fi through the “Gree+” app and be controllable from your phone normally.
- Same network environment: the Home Assistant host (such as a Raspberry Pi or a soft router) and the Gree air conditioner must be on the same local network (the same router).
- Note: the official integration relies on automatic discovery, so if the device is on a different subnet (VLAN) it may not be found.
Wi-Fi band: air conditioners usually only support 2.4GHz Wi-Fi.
Step 1: Add the integration in Home Assistant
- Open Home Assistant Log in to your Home Assistant backend in a browser or the app.
- Go to Devices & Services
- Click Settings in the left sidebar.
- Select Devices & Services.
Add the integration
- Click the + ADD INTEGRATION button in the bottom right corner.
- Type Gree in the search box.
- Click the Gree Climate icon in the search results.
Automatic device discovery
- After clicking, the system will automatically scan the local network for Gree devices.
- Case A: automatic discovery succeeds (recommended)
- The interface will display the discovered device (usually shown as a MAC address or a default name).
- Click Submit.
- You can choose an Area for the device (for example, Living Room or Master Bedroom), then click Finish.
Case B: no device found
- If the spinner keeps turning for a long time and then reports “no devices found”, check whether the air conditioner is powered on, whether Wi-Fi is working, and whether it is on the same network as the HA host.
- Beginner tip: try assigning a static IP to the air conditioner in your router admin panel, then restart the air conditioner and Home Assistant and try again.
Step 2: Control and use
Once added successfully, your air conditioner is integrated into Home Assistant.
- Find the entity
- Go back to Settings -> Devices & Services.
- Click the 1 device (or more) on the Gree Climate card.
- Click through to the device detail page.
Control panelYou will see a standard thermostat card with the following functions:
- Mode switching: Cool, Heat, Auto, Fan only, Dry, Off.
- Temperature adjustment: drag the ring or click the arrows to set the target temperature.
- Auxiliary switches: the system usually generates some extra switch entities automatically, for example:
- Panel Light: controls the LED display on the air conditioner body.
- Quiet: quiet mode.
- XFan: dry / auxiliary heat function.
Add to dashboard
- On the device detail page, click the “Add to dashboard” button to place the air conditioner card on your home page for easy everyday control.
FAQ and troubleshooting
Q1: Why can’t the device be found?
- Reason 1: network isolation. If your router has “AP isolation” enabled, or HA and the air conditioner are on different subnets, broadcast packets cannot get through and the official integration cannot discover it automatically.
- Solution: make sure both are connected to the same Wi-Fi signal (2.4G).
Reason 2: the device model is too old or too new.
- Solution: the vast majority of devices that support the Gree+ app are supported. If it really does not work, you may need to restart the air conditioner once (power it off and reconnect).
Q2: It shows “Unavailable” after being added?
- This usually means the air conditioner went offline. The Wi-Fi module of a Gree air conditioner occasionally goes to sleep after a long standby period. Try turning it on with the remote, or bind a static IP address in the router to improve stability.
Q3: What if the official integration is not good enough?
- If you are an advanced user and the official integration cannot meet your needs (for example, you need cross-subnet control), you can try installing the third-party Gree Climate Component through HACS, which supports manual IP address entry. However, for beginners it is strongly recommended to use the official integration above.
Verified environment notes
- Verified version: Home Assistant Core 2025.12.2
- Verified device: a generic Wi-Fi air conditioner supporting the Gree+ protocol
- Integration type: Official Core Integration (no HACS required)
About the author — Laite Intelligent was founded in 2010 and focuses on complete smart home solutions. Now ALL IN Home Assistant.
