Skip to main content

Govee Local API

Upload Python Package

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

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 original OSError (errno preserved; an EADDRINUSE is preferred when several differ), never a wrapper type, so errno-based handling keeps working.
  • bind_failures lists (address, OSError) pairs for the most recent start() only and is reset on every call. Partial success is also logged at warning level.
  • The configured address set is never pruned: a later start() retries every address, and rebind_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_failures with 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 and cleanup() was not called); otherwise it raises RuntimeError — use start() 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

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)

Source distribution for govee-local-api 3.3.1
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)

Table of built distributions (wheels) for govee-local-api 3.3.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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

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