Skip to main content

Python package

Gree Climate

Discover, connect and control Gree based mini-split systems.

greeclimate is a fully async Python3 based package for controlling Gree based ACs and heat pumps. Gree is a common brand for mini-split systems and is licensed and resold under many product names. This module should work for any device that also works with the Gree+ app, but has been tested on

  • Proklima mini-splits units
  • Trane mini-split heat pump (4TXK38)

If you have tested and know of others systems that work, please fork and submit a PR with the make and model

Cloud-only Gree Devices (and how to make them local again)

Gree has started making some devices cloud only, fortunately most of those devices can be downgraded and even made to fully drop the Gree cloud and telemetry connection using patched firmware.

See Gree Firmware Downgrader (and Patcher)

Getting the package

The easiest way to grab greeclimate is through PyPI pip3 install greeclimate

Use Gree Climate

Simple example showing how to discover and bind to devices on the LAN

import asyncio

from greeclimate.device_factory import create_device
from greeclimate.discovery import Discovery


async def main():
    discovery = Discovery()
    try:
        for device_info in await discovery.scan(wait_for=5):
            device = create_device(device_info)
            try:
                await device.bind()
                print(device_info.name, device_info.ip)
            finally:
                device.close()
    finally:
        discovery.close()


asyncio.run(main())

Scan a known IP address instead of broadcasting on the LAN.

from ipaddress import IPv4Address

devices = await discovery.scan(
    wait_for=5, target_addresses=[IPv4Address("192.0.2.10")]
)

Discover a device listening on UDP port 7000, including loopback addresses.

discovery = Discovery(allow_loopback=True)
devices = await discovery.scan(wait_for=5)

Manually poll for updated device state.

await device.update_state()

Request exact status columns and access raw protocol properties by name.

await device.update_state(["Pow", "Lig"])
# Read the cache after a DATA reply arrives.
print(device.get_property("Pow"))
device.set_property("Lig", 0)
await device.push_state_update()

Iterate through children from a Gateway device

from greeclimate.gateway import GatewayDevice
from greeclimate.network import Response

gateway = create_device(device_info)
if not isinstance(gateway, GatewayDevice):
    raise TypeError("Select a MID 60 gateway")
try:
    await gateway.bind()
    for child in await gateway.get_sub_devices():
        if not child.ready.is_set():  # Metadata-only commercial records.
            continue
        data_received = asyncio.Event()

        def on_child_data(data):
            if {"Pow", "Mod", "SetTem"} <= data.keys():
                data_received.set()

        child.add_handler(Response.DATA, on_child_data)
        try:
            await child.update_state(["Pow", "Mod", "SetTem"])
            await asyncio.wait_for(data_received.wait(), timeout=5)
            print(child.device_info.name, dict(child.raw_properties))
            child.set_property("Mod", 2)
            child.set_property("SetTem", 22)
            child.set_property("Pow", 1)
            await child.push_state_update()
            data_received.clear()
            await child.update_state(["Pow", "Mod", "SetTem"])
            await asyncio.wait_for(data_received.wait(), timeout=5)
            print(child.get_property("Pow"), child.get_property("SetTem"))
        finally:
            child.remove_handler(Response.DATA, on_child_data)
finally:
    gateway.close()  # Also closes every owned child.

For an AC, cool to 25°C and send updates to the device.

from greeclimate.device import Mode, TemperatureUnits

device.power = True
device.mode = Mode.Cool
device.temperature_units = TemperatureUnits.C
device.target_temperature = 25
await device.push_state_update()

Set a Fahrenheit target by selecting units before setting the temperature.

from greeclimate.device import TemperatureUnits

device.temperature_units = TemperatureUnits.F
device.target_temperature = 77
await device.push_state_update()

Set fan speed and swing positions.

from greeclimate.device import FanSpeed, HorizontalSwing, VerticalSwing

device.fan_speed = FanSpeed.Auto
device.horizontal_swing = HorizontalSwing.FullSwing
device.vertical_swing = VerticalSwing.FullSwing
await device.push_state_update()

Enable optional features where supported by the device.

device.light = True
device.xfan = True
device.quiet = True
await device.push_state_update()

Use capability evidence to offer an optional AC control without treating unknown as unsupported.

if device.capabilities["quiet"] is True:
    device.quiet = True
    await device.push_state_update()

Turn the device off, then request a fresh status update.

device.power = False
await device.push_state_update()
await device.update_state()

Use Gree Emulator

List supported simulated profiles and their exact MID values.

python -m gree_emulator --list-profiles

Run one simulated AC on loopback, with stable identity across restarts.

python -m gree_emulator --profile sim-w04n-v17 --mid 10001 --seed demo --listen 127.0.0.1

Run three independently controlled simulated ACs on the same endpoint.

python -m gree_emulator --profile sim-w04n-v17 --mid 10001 --count 3 --seed demo --listen 127.0.0.1

Run the supplied mixed-device configuration, including gateways and child devices.

python -m gree_emulator --config examples/emulator-devices.json

Run the simulated air-to-water heat pump (the 9301 and 9302 profiles remain raw-client families).

python -m gree_emulator --profile sim-w06a-p3-v6.04-9300 --mid 9300 --seed demo --listen 127.0.0.1

Expose the simulated ACs to LAN discovery on UDP port 7000, on a trusted test network only.

python -m gree_emulator --profile sim-w04n-v17 --mid 10001 --count 3 --seed demo --listen 0.0.0.0 --port 7000

Capture packet logs on stderr while keeping startup announcements on stdout; scrub identities, addresses, and bind exchanges before sharing.

python -m gree_emulator --profile sim-w04n-v17 --mid 10001 --seed demo --listen 127.0.0.1 2> emulator-packets.log

Device and protocol reference

Debugging

Maybe the reason you're here is that you're working with Home Assistant and your device isn't being detected.

There are a few tools to help investigate the various compatibility problems that Gree based devices present.

Below is a series of tests, please run them and use their output in issue reports. Additionally using Wireshark or tcpdump to capture the network traffic can greatly assist in investigations.

Setup

This presumes you have python installed

pip install -r requirements.txt

Getting some basic information about your network

Linux / OSX

sudo route -n
sudo ifconfig

Windows command line

route print -4
ipconfig

Running the discovery tests

First test is to check the response of devices when trying to discovery them, writes the results to discovery_results.txt. Use Wireshark here if you can.

python gree.py --discovery > discovery_results.txt

Metadata

Release files for greeclimate 4.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for greeclimate 4.3.1
File Size Uploaded Provenance Actions
greeclimate-4.3.1.tar.gz 708.5 kB With provenance Details for greeclimate-4.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for greeclimate 4.3.1
File Interpreter ABI Platform Actions
greeclimate-4.3.1-py3-none-any.whl Python 3 none any Details for greeclimate-4.3.1-py3-none-any.whl

Total release size: 1.1 MB

Release files / greeclimate-4.3.1.tar.gz

Download URL greeclimate-4.3.1.tar.gz
Size 708.5 kB
Tags Source
SHA-256 checksum
How to use checksums
78e0627ca562859df5cc0356c6c354607e2d0263d46be3262d0280ba5b698866
BLAKE2b-256 checksum
How to use checksums
b9626dee45c1480707537e2e0e62bf5f28c9d34ed29f3d2172f90cb1247a189b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / greeclimate-4.3.1-py3-none-any.whl

Download URL greeclimate-4.3.1-py3-none-any.whl
Size 428.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2a88677b7453d3b1b2070e8bf29c36472ec3b569414e8b516ac9bbe386854cc0
BLAKE2b-256 checksum
How to use checksums
cf0c507c2620d6b9e2d44e16816d675c4330c2e80808a9c8c42e28f0d1c5eba6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for greeclimate 4.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for greeclimate-4.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

4.3.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page