Getting started


You can install the most recent release using pip:

pip install python-miio

Alternatively, you can clone this repository and use poetry to install the current master:

git clone
cd python-miio/
poetry install

This will install python-miio into a separate virtual environment outside of your regular python installation. You can then execute installed programs (like miiocli):

poetry run miiocli --help


If you want to execute more commands in a row, you can activate the created virtual environment to avoid typing poetry run for each invocation:

poetry shell
miiocli --help
miiocli discover

Device discovery

Devices already connected to the same network where the command-line tool is run are automatically detected when miiocli discover is invoked. This command will execute two types of discovery: discovery by handshake and discovery by mDNS. mDNS discovery returns information that can be used to detect the device type which does not work with all devices. The handshake method works on all MiIO devices and may expose the token needed to communicate with the device, but does not provide device type information.

To be able to communicate with devices their IP address and a device-specific encryption token must be known. If the returned a token is with characters other than 0s or fs, it is likely a valid token which can be used directly for communication.

Obtaining tokens

The miiocli tool can fetch the tokens from the cloud if you have micloud package installed. Executing the command will prompt for the username and password, as well as the server locale to use for fetching the tokens.

miiocli cloud list

Alternatively, see our documentation for other ways to obtain the tokens.

You can also access this functionality programatically using

Environment variables for command-line tools

To simplify the use, instead of passing the IP and the token as a parameter for the tool, you can simply set the following environment variables. The following works for mirobo, for other tools you should consult the documentation of corresponding tool.

export MIROBO_IP=
export MIROBO_TOKEN=476e6b70343055483230644c53707a12