Govee Local API
Please note that scene and segment support is still very experimental.
See SUPPORTED_DEVICES.md for the full list of known device models and their capabilities.
Requirements
- Python >= 3.11
- Govee Local API enabled. Refer to https://app-h5.govee.com/user-manual/wlan-guide
Installation
From your terminal, run
pip install govee-local-api
or
python3 -m pip install govee-local-api
Usage
Basic Usage
import asyncio
from govee_local_api import GoveeController
async def main():
# Simple single-interface setup
controller = GoveeController()
# Discover devices
devices = await controller.scan_devices()
# Control a device
if devices:
device = devices[0]
await device.turn_on()
await device.set_brightness(80)
await device.set_color(255, 0, 0) # Red
asyncio.run(main())
Multi-Interface Setup
For complex network environments with multiple interfaces:
# Multiple listening addresses (basic)
controller = GoveeController(
listening_addresses=["192.168.1.100", "10.0.0.100", "172.16.1.100"]
)
Tolerating a failed bind (require_all=False)
By default start() requires every configured address to bind; a single failure
(EADDRNOTAVAIL for a stale address, EADDRINUSE, an interface that went down)
closes any endpoint already opened and re-raises, so the controller is left unbound.
Since 3.1.0 you can opt in to keeping whatever binds successfully:
controller = GoveeController(
listening_addresses=["192.168.1.100/24", "10.0.0.100/8", "172.16.1.100/16"]
)
await controller.start(require_all=False)
for address, error in controller.bind_failures:
logging.warning("Not listening on %s: %s", address, error)
print("Live on", controller.listening_addresses)
start()raises only if no address binds. The raised exception is the originalOSError(errno preserved; anEADDRINUSEis preferred when several differ), never a wrapper type, soerrno-based handling keeps working.bind_failureslists(address, OSError)pairs for the most recentstart()only and is reset on every call. Partial success is also logged atwarninglevel.- The configured address set is never pruned: a later
start()retries every address, andrebind_failed()(below) retries only the missing ones without restarting.
Recovering interfaces that come back (rebind_failed())
To pick up an adapter that was down at startup (or an endpoint that later closed unexpectedly)
without tearing down the live endpoints or losing the discovered devices, call
rebind_failed() — e.g. on a timer or a network-change event:
recovered = await controller.rebind_failed()
if recovered:
print("Back on", recovered)
for address, error in controller.bind_failures:
logging.warning("Still not listening on %s: %s", address, error)
- Only the configured addresses that are not currently live are retried; live endpoints are untouched and a recovered address returns to its configured position.
- It never raises for a bind failure: addresses that still fail stay in
bind_failureswith the fresh error, and the addresses that came back are removed from it. It returns the list of addresses bound by that call. - A successful rebind sends a discovery burst right away (when discovery is enabled) so devices on the recovered interface show up without waiting for the next tick.
- It requires a running controller (
start()succeeded andcleanup()was not called); otherwise it raisesRuntimeError— usestart()in that case.
Network Mask Configuration
For precise subnet-aware device routing (recommended for enterprise/VLAN environments), embed the network mask directly in the address using CIDR or netmask notation:
# Precise subnet matching with embedded network masks
controller = GoveeController(
listening_addresses=[
"192.168.1.100/24", # Main LAN (CIDR)
"192.168.10.100/255.255.255.0", # IoT VLAN (dotted netmask)
"10.0.0.100/8" # Management network
]
)
Supported Network Mask Formats
- CIDR Notation:
192.168.1.100/24,10.0.0.100/8, etc. - Dotted Decimal:
192.168.1.100/255.255.255.0, etc. - No mask:
192.168.1.100(uses heuristic subnet matching) - Wildcard:
0.0.0.0(listens on all interfaces, no subnet matching)
Advanced Features
Device Discovery and Control
async def discover_and_control():
controller = GoveeController(
listening_addresses=["192.168.1.100/24", "192.168.10.100/24"]
)
# Scan for devices across all networks
devices = await controller.scan_devices()
# Filter devices by network
main_lan_devices = [d for d in devices if d.ip.startswith("192.168.1.")]
iot_vlan_devices = [d for d in devices if d.ip.startswith("192.168.10.")]
# Control devices on specific networks
for device in main_lan_devices:
await device.turn_on()
await device.set_brightness(50)
for device in iot_vlan_devices:
await device.turn_off()
Direct Device Control
# Control device by IP address (uses intelligent transport selection)
await controller.control_device("192.168.1.100", turn_on=True)
await controller.control_device("192.168.1.100", brightness=75)
await controller.control_device("192.168.1.100", color_rgb=(0, 255, 0))
Color Temperature Range
Most models accept white light between 2000 K and 9000 K. Models with a different range declare their own, and commands are clamped to it:
device.temperature_range # GoveeTemperatureRange(min_kelvin=2000, max_kelvin=9000)
min_kelvin, max_kelvin = device.temperature_range
await device.set_temperature(9000) # clamped to the model's maximum
Register a model with a custom range in GOVEE_LIGHT_CAPABILITIES:
"H0000": create_with_capabilities(
True, True, True, 0, True, temperature_range=(2700, 6500)
),
Library Scenes
set_scene() plays one of the model's firmware scenes, listed in
device.capabilities.available_scenes. They come from Govee's per-model scene
library and are the ones that play from their scene code alone; see
SUPPORTED_DEVICES.md for each model's list.
await device.set_scene("sunset")
The rest of the library's scenes (most of the ones the Govee app shows) need a parameter blob and can be sent with their library code and that blob:
# "Halloween B" on an H706C: sceneCode and base64-decoded scenceParam
# from the model's scene library entry
await device.set_scene_code(11158, scene_param)
await device.set_scene_code(8) # a scene without parameters
Obtaining the library is outside the scope of this package. The encoding is the one used by govee2mqtt.
Documentation
- Supported Devices - Auto-generated list of known device models and their capabilities
- Network Mask Configuration Guide - Comprehensive guide for multi-network setups
- API Reference - Full API documentation
Use Cases
- Home Networks: Simple single-interface setup
- Small Office: Multi-interface with heuristic matching
- Enterprise/VLAN: Network mask configuration for precise routing
- IoT Deployments: Isolated network segments with dedicated interfaces
- Multi-Building: Physically separated networks with same IP ranges
Metadata
Release files for govee-local-api 3.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| govee_local_api-3.3.1.tar.gz | 35.9 kB | With provenance | Details for govee_local_api-3.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| govee_local_api-3.3.1-py3-none-any.whl | Python 3 | none | any | Details for govee_local_api-3.3.1-py3-none-any.whl |
Total release size: 74.1 kB
Release files / govee_local_api-3.3.1.tar.gz
| Download URL | govee_local_api-3.3.1.tar.gz |
|---|---|
| Size | 35.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0cd47ca23484706e19f544bbf658ccdbb207a23abb4d720775aa69e198ec895b
|
|
BLAKE2b-256 checksum How to use checksums |
0a67d922a6b3ae26ddb42aca78eeaf9b1a60d6b73187f8845f98133a4ec91065
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
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 Oct 25, 2026.
Transparency logRelease files / govee_local_api-3.3.1-py3-none-any.whl
| Download URL | govee_local_api-3.3.1-py3-none-any.whl |
|---|---|
| Size | 38.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3b0a113d383efe903bde61f9b447aaa5691052aef488d9fa3b4bb6c28c7a12c8
|
|
BLAKE2b-256 checksum How to use checksums |
6bbbd75141da5e91ec3a18de649ea6aab729c3b1e1cfec15b541e792a6ed0cc7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
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 Oct 25, 2026.
Transparency logSecurity for govee-local-api 3.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.
Attestation for govee_local_api-3.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 Oct 25, 2026.
Transparency logA 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.