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

Based on the following work

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.2.5

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.2.5
File Size Uploaded Provenance Actions
greeclimate-4.2.5.tar.gz 707.6 kB With provenance Details for greeclimate-4.2.5.tar.gz

Built distribution (wheel)

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

Total release size: 1.1 MB

Release files / greeclimate-4.2.5.tar.gz

Download URL greeclimate-4.2.5.tar.gz
Size 707.6 kB
Tags Source
SHA-256 checksum
How to use checksums
c1be51fed6f8ee14e804334d3738367b536fb91571ae69aa69798e83d5202488
BLAKE2b-256 checksum
How to use checksums
ad4591cb0282916f5a3ae34dc9efa6408628fe5d0e8cd0d6852e6d370a9f9cae
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 12, 2026.

Transparency log

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

Download URL greeclimate-4.2.5-py3-none-any.whl
Size 427.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
571c0e9674a8de0519c92d44861b7e77ab55f46ed77585b4a5ba326ec7f44976
BLAKE2b-256 checksum
How to use checksums
742fceec8aa68068ef0097659719b3f9a6a828b61c2f9335b01cb7f03d5cd864
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 12, 2026.

Transparency log

Security for greeclimate 4.2.5

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.2.5.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 12, 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.2.5 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