greeclimate

What it is and what it does

greeclimate is a fully async Python library for controlling Gree-branded mini-split HVAC systems (air conditioners and heat pumps) that are also compatible with the Gree+ mobile app. It handles network discovery, device binding with encryption key negotiation, and state management for properties like power, temperature, fan speed, and operating mode. The library uses netifaces for network interface detection and pycryptodome for the two-layer encryption scheme that Gree devices employ.

The package is designed for home automation integrations and has been tested on Proklima and Trane mini-split units. It provides async methods for scanning the network, binding to discovered devices, querying current state, and pushing configuration changes. The binding process is described as finnicky—devices only respond to binding requests immediately following a network scan, and re-binding may be necessary if the device key is lost.

Use it for:

• Integrate Gree mini-split systems into Home Assistant or other home automation platforms for centralized climate control.
• Build custom monitoring dashboards that query device state (temperature, mode, fan speed) over the network.
• Automate HVAC scheduling by setting power, target temperature, and operating mode via async Python scripts.
• Troubleshoot device connectivity issues using the built-in discovery and diagnostic tools.
• Control multiple Gree units concurrently in a single application using async/await patterns.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Async Python library for discovering, connecting to, and controlling Gree-based mini-split air conditioning and heat pump systems over the network.

Yes, if you own a Gree-compatible mini-split system and need programmatic control. The package is actively maintained, has low install friction, and provides a clean async API. The main gotcha is that device binding is finnicky and requires immediate re-scan if the device key is lost—test discovery and binding thoroughly before relying on it in production. GPLv3 licensing means any derivative work must remain open-source.

Install

greeclimate on PyPI

pip install greeclimate

uv add greeclimate

poetry add greeclimate

Installing greeclimate

Before you install

Low install friction with only two runtime dependencies (netifaces and pycryptodome). Package is actively maintained with recent commits and supports current Python versions (3.10+).

License in practice

Licensed under GPLv3 (copyleft). Any derivative work or bundled distribution must also be open-source under compatible terms.

Quickstart

pip install greeclimate

from greeclimate.discovery import Discovery
from greeclimate.device import Device

discovery = Discovery()
for device_info in await discovery.scan(wait_for=5):
    device = Device(device_info)
    await device.bind()

Requires Python 3.10 or later. Binding to devices is finnicky and only works immediately after a network scan; devices must be on the same network and discoverable via UDP broadcast.

Verify before relying

• Whether all Gree+ app-compatible devices are actually supported or only specific models
• Exact encryption key negotiation details and whether re-binding is always required after power loss
• Whether the package handles concurrent connections to multiple devices reliably

Package facts

Evidence: greeclimate-3.2.0-py3-none-any.whl

Tags

More Networking packages