CLI tool
rytilahti/python-miio avatar
rytilahti/python-miio

python-miio ships three console commands and one dev tag standing in for a release

Python library & console tool for controlling Xiaomi smart appliances

4,339 stars600 forksPythonGPL-3.0

At a glance

What is it?
python-miio is a GPL library plus the miiocli command line tool for talking to Xiaomi appliances over miIO and MIoT, and the two paths are not installed the same way. The front page tells you to pip install the latest release while telling you twice that MIoT support needs the git checkout or a pre-release, and the newest release is still a 0.6.0 dev tag from 2024.
Who is it for?
python-miio is the right tool when you own the device and want local control instead of a cloud round trip, and the genericmiot path covers models that have no dedicated module yet. Verify three things before you build on it.
Can I use it commercially?
Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?
Yes. The repository last received commits 113 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • rytilahti/python-miio4,339 ★ · +33
Star history
Repository2026-09-232026-11-15
rytilahti/python-miio4.3k4.3k

33 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The documented pip install does not contain the MIoT integration

The installation section opens with the release path:

code
pip install python-miio

and offers the development version as an alternative:

code
pip install git+https://github.com/rytilahti/python-miio.git

What complicates the choice is stated twice, once at the end of the install section and again at the end of the MIoT section. Both notes say the project is in the middle of a major refactoring effort, and that anyone controlling modern MIoT devices should use the git version or a pre-release, `pip install --pre python-miio`, until version 0.6.0 is released. So the first command on the page is the wrong one for the integration the page spends the next section teaching.

The wait has been long. The newest published release is 0.6.0.dev0, dated 2024-03-13, the two before it are 0.5.12 from 2022-07-18 and 0.5.11 from 2022-03-07, and the default branch `master` has been pushed to on 2026-07-25. The version in pyproject.toml is still `0.6.0.dev0`, the same string as the newest release.

Installing puts three commands on PATH, and only one of them is documented

The packaging metadata defines three console scripts rather than one. `miiocli` maps to `miio.cli:create_cli`, `miio-extract-tokens` maps to `miio.extract_tokens:main`, and `mirobo` maps to `miio.integrations.roborock.vacuum.vacuum_cli:cli`.

The third one is the interesting case. `mirobo` is installed from the same metadata as `miiocli`, pointing at a module nested three directories deep inside the roborock integration. Every example on the front page uses `miiocli`, including the roborock commands themselves.

The token extractor is the other undocumented surface: `miio-extract-tokens` is a separate entry point from the `miiocli cloud` command that the getting started section recommends. The README also points to the documentation for other ways to obtain tokens.

Every invocation tries to identify the device through the cloud first

Each command run starts by working out what the device is. The front page says each invocation automatically tries to detect the device model, and names the failure case: when the device has no cloud connectivity that information may not be available, which causes an error. The way out is to name the model yourself and skip detection:

code
miiocli roborockvacuum --model roborock.vacuum.s5 --ip <ip> --token <token> start

So a vacuum on an isolated network needs a model string baked into every command, which means knowing the internal identifier rather than the product name.

The generic `info` command is the escape hatch for discovery, and it works on devices the library has no module for:

code
Model: rockrobo.vacuum.v1
Hardware version: MW300
Firmware version: 1.2.4_16
Supported using: RoborockVacuum
Command: miiocli roborockvacuum --ip 127.0.0.1 --token 00000000000000000000000000000000
Supported by genericmiot: True

Two details in that output are worth pausing on. The `Supported using` line prints a Python class name rather than a user-facing device name, and the `Command` line hands you a ready-made command line with the connection arguments already filled in.

miiocli cloud reads an account password and prints device tokens in clear

Token acquisition is documented as a single interactive command:

code
Username: [email protected]
Password:

== name of the device (Device offline ) ==
    Model: example.device.v1
    Token: b1946ac92492d2347c6235b4d2611184
    IP: 192.168.xx.xx (mac: ab:cd:ef:12:34:56)
    DID: 123456789
    Locale: cn

The credential handling happens inside a third party package rather than in this repository. The page says the tokens are fetched from the cloud account using micloud, and `micloud>=0.6` is a hard dependency in the project metadata, so a cloud login for the appliance vendor runs through someone else's code on every call to this command.

What comes back is the device token, its local IP, the MAC address, the device id and the account locale, all printed to the terminal in clear. That token is the same value later passed to `--token` on every other command. Anyone who runs this on a shared machine, pastes the output into a chat, or commits it by accident has published the key to those devices. The example output also shows a device reported as offline alongside its credentials, which suggests the fetch succeeds independently of the device being reachable.

genericmiot turns a downloaded spec file into four commands

The MIoT path avoids per-device modules by reading a model description file. The integration uses miot spec files to work out which sensors, settings and actions a device exposes, and the file for a specific device model is downloaded and cached locally the first time that model is queried.

Four commands cover everything the spec exposes: `status` shows current state, `set` changes a setting, `actions` lists what can be invoked, and `call` invokes one. Settings are addressed by a dotted name such as `light:brightness`, and `status` reports each property with its access, its numeric bounds and the Python type it parses into.

What `set` prints back shows how thin the generic layer really is:

code
[{'did': 'light:brightness', 'siid': 2, 'piid': 3, 'code': 0}]

A write is a service id and a property id pair with a result code, and an action call answers with `{'code': 0, 'out': []}`.

The metadata calls itself production stable while the version stays a dev tag

The project metadata declares `Development Status :: 5 - Production/Stable`, sets the version to `0.6.0.dev0`, and requires Python `>=3.11`, with classifiers for 3.11, 3.12 and 3.13 and nothing below that. The status classifier and the version string point in opposite directions, and the front page adds its own framing by describing an ongoing major refactoring effort.

The dependency list is where the library's scope shows. Alongside the expected `click`, `cryptography` and `attrs` sit `pydantic>=2`, `construct>=2.10.56,<3`, `zeroconf`, `croniter>=1`, `defusedxml`, and `micloud>=0.6` for cloud token retrieval. Upper bounds appear on construct, zeroconf, tqdm, defusedxml and PyYAML.

The licensing is GPL-3.0-only, declared in the metadata license field. That matters for anyone planning to bundle this into a larger tool rather than run it as a command line utility.

uv, pre-commit and a changelog generator share the repository root

The build tooling has moved on from a plain setup script. The root carries `pyproject.toml`, a `uv.lock` file, `.pre-commit-config.yaml`, `.flake8`, `.readthedocs.yml`, a `.github_changelog_generator` file, `RELEASING.md`, `CHANGELOG.md`, `devtools/`, `docs/` and the `miio/` package itself. The dependency groups live in pyproject as well, listing pytest with its async and mock plugins, mypy pinned to CPython, coverage, isort, docformatter, tox and doc8.

Optional extras are grouped by task rather than by device. `docs` pulls Sphinx with the read-the-docs theme and myst-parser, `updater` pulls `netifaces>=0,<1`, `backup_extract` pulls `android_backup>=0,<1`, and `crcmod` pins that library to `>=1.7,<2`. The backup extractor is the notable one: it brings in an Android backup parser.

The front page also has sections for simulators, supported devices, projects using the library and other related projects.

Editorial conclusion

python-miio is the right tool when you own the device and want local control instead of a cloud round trip, and the genericmiot path covers models that have no dedicated module yet. Verify three things before you build on it. First, decide whether you are on the released 0.5.x line or the unreleased 0.6.0 dev line, because the MIoT integration only exists on the second and the front page says so in two separate notes. Second, know that model detection runs on every invocation and can fail when the device has no cloud connectivity, so such a device needs `--model` spelled out. Third, keep the tokens out of shell history and screenshots, since `miiocli cloud` prints them in clear and the same value is what every later command passes to `--token`.

Frequently asked questions

How do I get the device tokens that python-miio needs?

The documented route is `miiocli cloud`, which prompts for a username and password and then prints each device with its model, token, IP address, MAC, device id and locale. The fetch runs through the micloud package, a separate project that python-miio depends on directly. The docs page on discovery is pointed to for other ways of obtaining tokens.

Does `pip install python-miio` give me the modern MIoT device support?

Not according to the project's own note, which appears twice: for MIoT devices it tells you to use the git version or `pip install --pre python-miio` until version 0.6.0 is released. The newest published release is 0.6.0.dev0 from 2024-03-13.

What Python version does python-miio require?

`>=3.11`, with classifiers for 3.11, 3.12 and 3.13 and no support declared below 3.11. The project also keeps a uv lock file at the root, alongside pre-commit and flake8 configuration.

Which commands does installing python-miio put on my PATH?

Three: `miiocli`, `miio-extract-tokens`, and `mirobo`. The last one points at `miio.integrations.roborock.vacuum.vacuum_cli:cli`, while every example on the front page uses `miiocli`.

What does the genericmiot integration in python-miio actually do?

It downloads and caches the miot spec file for a device model on first use, then exposes four commands: `status`, `set`, `actions` and `call`. Properties are addressed by names like `light:brightness`, and writes resolve to a service id and property id pair, for example `[{'did': 'light:brightness', 'siid': 2, 'piid': 3, 'code': 0}]`.

Official sources

  1. License: GPL-3.0
  2. Project website
  3. README
  4. Releases
  5. rytilahti/python-miio on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/rytilahti-python-miio.svg)](https://hysenlabs.com/projects/rytilahti-python-miio)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/rytilahti-python-miio.svg)](https://hysenlabs.com/projects/rytilahti-python-miio)

Was this useful?