Python client for OverKiz API

A fully asynchronous and user-friendly API client for the OverKiz platform. This client enables interaction with smart devices connected to OverKiz, supporting multiple vendors such as Somfy TaHoma and Atlantic Cozytouch.

This package is primarily used by Home Assistant Core to provide the Overkiz integration. If you wish to use this package in your own project, refer to the full documentation, the example below, or explore the Home Assistant source code for additional usage examples.

Documentation

Full documentation is available at imicknl.github.io/python-overkiz-api:

Getting started — cloud and local API setup
Core concepts — clients, servers, credentials, and models
Device control and event handling
Migrating from v1
SDK reference

Supported hubs

Vendor	Cloud	Local
Atlantic Cozytouch	✓
Bouygues Flexom	✓
Brandt Smart Control	✓
Hexaom HexaConnect	✓
Hitachi Hi Kumo	✓
Nexity Eugénie	✓
Rexel Energeasy Connect †	✓	✓
Sauter Cozytouch	✓
Sauter Smart Control	✓
Simu LiveIn2	✓
Somfy	✓	✓
Thermor Cozytouch	✓
Ubiwizz	✓

Local API availability depends on your specific gateway. See the Getting started guide for the supported gateways and setup.

† The cloud API requires OAuth credentials provided by Rexel; the local API uses a token from the EConnect app instead.

Somfy

Gateway	Cloud	Local
Connexoon IO	✓	✓
Connexoon RTS	✓	✓
TaHoma v2	✓	✓
TaHoma Beecon	✓	✓
TaHoma Switch	✓	✓
Connectivity Kit	✓

Rexel Energeasy Connect

Gateway	Cloud	Local
Energeasy Connect	✓
Energeasy Connect Rail Din	✓	✓
Energeasy Connect V2	✓	✓
Energeasy Connect V3	✓	✓
Energeasy Connect V3 Rail Din	✓	✓

Installation

pip install pyoverkiz

Getting started

Connect to the cloud API, authenticate, and list your devices:

import asyncio

from pyoverkiz.auth.credentials import UsernamePasswordCredentials
from pyoverkiz.client import OverkizClient
from pyoverkiz.enums import Server


async def main() -> None:
    async with OverkizClient(
        server=Server.SOMFY_EUROPE,
        credentials=UsernamePasswordCredentials("username", "password"),
    ) as client:
        await client.login()

        devices = await client.get_devices()
        for device in devices:
            print(f"{device.label} ({device.device_url}) - {device.controllable_name}")


asyncio.run(main())

For executing commands, listening to events, and connecting to the local API, see the Getting started guide in the documentation.

Projects using pyOverkiz

This package powers the Overkiz integration in Home Assistant Core. Other open-source projects and custom automations also leverage pyOverkiz to interact with Overkiz-compatible hubs and devices, including:

overkiz2mqtt: Bridges Overkiz devices to MQTT for integration with various platforms.
mcp-overkiz: Implements an MCP server to enable communication between Overkiz devices and language models.
tahoma: Command Line Interface (CLI) to control Overkiz devices.

Contribute

We welcome contributions! To get started with setting up this project for development, follow the steps below.

Project setup

Dev Container (recommended)

If you use Visual Studio Code with Docker or GitHub Codespaces, you can take advantage of the included Dev Container. This environment comes pre-configured with all necessary dependencies and tools, including the correct Python version, making setup simple and straightforward.

Manual setup

Install uv.
Clone this repository and navigate to it: cd python-overkiz-api
Initialize the project with uv sync, then run uv run prek install

Tests

uv run pytest

Metadata

Release files for pyoverkiz 2.3.0

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

Source distribution (sdist)

Source distribution for pyoverkiz 2.3.0
File	Size	Uploaded	Provenance
pyoverkiz-2.3.0.tar.gz	129.3 kB	Oct 24, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for pyoverkiz 2.3.0
File	Interpreter	ABI	Platform	Reset
pyoverkiz-2.3.0-py3-none-any.whl 140.5 kB Oct 24, 2026 With provenance	Python 3	none	any	Details

Total release size: 269.7 kB

Release files / pyoverkiz-2.3.0.tar.gz

Download URL	pyoverkiz-2.3.0.tar.gz
Size	129.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`bb06e63ede0d244a98558eab329be2bd5f76262857e3f4febd88ad322f739669`
BLAKE2b-256 checksum How to use checksums	`81245f932c05f425bf01b9a2d10459c1320cefb80b092522838990a9133d137f`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/iMicknl/python-overkiz-api
Publishing commit: github.com/iMicknl/python-overkiz-api/tree/8e16863cba8e28f14c73e7e2800417e9f4a87637

Workflow

Publishing configuration: github.com/iMicknl/python-overkiz-api/blob/8e16863cba8e28f14c73e7e2800417e9f4a87637/.github/workflows/release.yml
Publishing logs: github.com/iMicknl/python-overkiz-api/actions/runs/40104699516/attempts/1

Artifact

Subject: pyoverkiz-2.3.0.tar.gz
SHA-256 checksum: bb06e63ede0d244a98558eab329be2bd5f76262857e3f4febd88ad322f739669 Verifying attestations

Release files / pyoverkiz-2.3.0-py3-none-any.whl

Download URL	pyoverkiz-2.3.0-py3-none-any.whl
Size	140.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1c51d5b5eaef09ebe10b10c4c3059b68ecff9d6d069d6ecf2e42d249572fd443`
BLAKE2b-256 checksum How to use checksums	`7d307ee105bcc39612fad7cf4e5ec99ba4a38b9d55b58d17074cdbeb8ce4ac4a`
Upload date	Oct 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/iMicknl/python-overkiz-api
Publishing commit: github.com/iMicknl/python-overkiz-api/tree/8e16863cba8e28f14c73e7e2800417e9f4a87637

Workflow

Publishing configuration: github.com/iMicknl/python-overkiz-api/blob/8e16863cba8e28f14c73e7e2800417e9f4a87637/.github/workflows/release.yml
Publishing logs: github.com/iMicknl/python-overkiz-api/actions/runs/40104699516/attempts/1

Artifact

Subject: pyoverkiz-2.3.0-py3-none-any.whl
SHA-256 checksum: 1c51d5b5eaef09ebe10b10c4c3059b68ecff9d6d069d6ecf2e42d249572fd443 Verifying attestations

Security for pyoverkiz 2.3.0

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for pyoverkiz-2.3.0.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/iMicknl/python-overkiz-api
Publishing commit: github.com/iMicknl/python-overkiz-api/tree/8e16863cba8e28f14c73e7e2800417e9f4a87637

Workflow

Publishing configuration: github.com/iMicknl/python-overkiz-api/blob/8e16863cba8e28f14c73e7e2800417e9f4a87637/.github/workflows/release.yml
Publishing logs: github.com/iMicknl/python-overkiz-api/actions/runs/40104699516/attempts/1

Artifact

Subject: pyoverkiz-2.3.0.tar.gz
SHA-256 checksum: bb06e63ede0d244a98558eab329be2bd5f76262857e3f4febd88ad322f739669 Verifying attestations

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.