Install & Compatibility
Where this runs
tested against v8.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 60.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 10.4s · import 0.000s · 60MB
54MB installed
● package 54MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ShellyDevice
✓ from aioshelly import ShellyDevice
✗ from aioshelly.device import ShellyDevice
Basic example: discover and control a Shelly Plug S (gen1) using CoAP.
import asyncio
import aiohttp
from aioshelly.factory import get_device
async def main():
async with aiohttp.ClientSession() as session:
# For local CoAP (gen1) device:
options = {
'ip_address': '192.168.1.100',
'auth': {'username': 'admin', 'password': ''}
}
device = await get_device(session, 'shellyplug-s-XXXX', options)
await device.async_setup()
print('Device name:', device.name)
print('Is on:', device.channels[0].state)
await device.channels[0].turn_on()
await device.async_update()
asyncio.run(main())
Debug
Known issues
breakingIn v10, top-level imports (from aioshelly import X) were removed. All classes/functions must be imported from their submodules (e.g., aioshelly.device, aioshelly.coap, aioshelly.factory).fixReplace 'from aioshelly import ShellyDevice' with 'from aioshelly.device import ShellyDevice' or use factory.
affects: >=10.0.0
deprecatedThe async_get_device() function was deprecated in v12 and removed in v13. Use get_device() from aioshelly.factory instead.fixReplace async_get_device() with get_device() from aioshelly.factory.
affects: >=12.0.0, <13.0.0 (deprecated); >=13.0.0 (removed)
gotchaDevice initialization must be awaited with device.async_setup() after get_device(). Forgetting this leads to AttributeError on device.channels.fixAlways call await device.async_setup() before accessing device properties.
affects: all
gotchaCoAP devices (gen1) require the local IP and auth credentials. If auth is wrong, device.update() may fail silently. For gen2/3 devices, use Cloud or local HTTP API with auth key.fixVerify auth credentials and use correct options dict with 'ip_address' and 'auth' for gen1, or 'auth_key' for gen2+.
affects: all
breakingIn v11, the 'channels' attribute changed from a dict to a list. Iterating over channels now yields indexes instead of channel numbers.fixAccess channels by index: device.channels[0].state instead of device.channels[0].state (or use dict-style if still needed, but prefer indexing).
affects: >=11.0.0
Upgrade
Version history
13.26.2latest on PyPI · released Jun 18, 2026
Audit
Dependencies
aiohttprequiredHTTP client for API calls
orjsonrequiredFast JSON parsing for CoAP messages
bleakoptionalBluetooth Low Energy communication (BLE)