Learn how to use the Python library to connect to the Arduino Cloud.

It is recommended to have some experience with the Python environment before reading this guide. However, installation and setup is covered in the Python Setup section.

The Arduino IoT Cloud Python Client is a library that allows you to interact with the Arduino Cloud via MQTT. It supports basic authentication using the device ID as well as secret key that is obtained from the Arduino Cloud when configuring a manual device.


In this guide we will:

  • Configure a manual device in the Arduino Cloud,
  • install the Arduino IoT Cloud Python library,
  • write a Python script that connects to the Arduino Cloud.


To follow this guide, make sure to have:

The experience with Python and the pip package manager varies depending on your computer and operating system. Python needs to be in your PATH to use the Arduino IoT Cloud Python client.

Cloud Setup

To begin with, we need to create a manual device, and create a new Thing. Navigate to the Arduino Cloud and to the "Things" tab.

Thing & Device Configuration

  1. Create a new Thing, by clicking on the "Create Thing" button.
  2. Click on the "Select Device" in the "Associated Devices" section of your Thing.
  3. Click on "Set Up New Device", and select the bottom category ("Manual Device"). Click continue in the next window, and choose a name for your device.
  4. Finally, you will see a new Device ID and a Secret Key generate. You can download them as a PDF. Make sure to save it as you cannot access your Secret Key again.

Device ID & Secret key.
Device ID & Secret key.

Create Variables

Next step is to create some Cloud variables, which we will later interact with via a Python script.

  1. While in Thing configuration, click on "Add Variable" which will open a new window.
  2. Name your variable
    and select it to be of an
  3. Click on "Add Variable" at the bottom of the window.
  4. Create another variable, name it
    and select it to be

You should now have two variables,

. It is important that they are named exactly like this, as we will be using them in the example script of this guide.

Complete Thing.
Complete Thing.

Variables that we create here can also be synchronized with variables running on any other device in the platform. This makes it possible to link an Arduino boards with a Python or JavaScript project without writing any connection code!

Python Setup

Before continuing, make sure you have a version of Python installed. You can check this by opening a terminal and running:

1python --version
2python3 --version

Install Packages

To install the Arduino IoT Cloud Python client, run the following command:

1pip install arduino-iot-cloud

You will also need to install the swig package.

1pip install swig

To test out to see if your installation worked correctly, start the Python interpreter in your terminal by typing

, once running, test out this command:

1from arduino_iot_cloud import ArduinoCloudClient

If you don't receive any import error, it means it is accessible and we can move on to testing out the example script.

Example Script

The script below creates a client that connects to the Arduino Cloud and synchronizes the variable values. Make sure to enter your device credentials (see Cloud Setup) in the


Create a python file, and name it something appropriate, such as
, and copy the contents of the code snippet below into it.

1import time
2import logging
4import sys
7from arduino_iot_cloud import ArduinoCloudClient
12def logging_func():
13 logging.basicConfig(
14 datefmt="%H:%M:%S",
15 format="%(asctime)s.%(msecs)03d %(message)s",
16 level=logging.INFO,
17 )
19# This function is executed each time the "test_switch" variable changes
20def on_switch_changed(client, value):
21 print("Switch Pressed! Status is: ", value)
23if __name__ == "__main__":
25 logging_func()
26 client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=SECRET_KEY)
28 client.register("test_value")
29 client["test_value"] = 20
30 client.register("test_switch", value=None, on_write=on_switch_changed)
32 client.start()
  • The script uses the
    to configure the variables.
  • The
    we simply set a static value of
  • For the
    variable, we create a callback function that is triggered any time the value is updated. This can be controlled from a dashboard in the Arduino Cloud.

To run this script, use the following command (or the "Run" button in VSCode):


After running the script, you should see in the terminal that we first attempt to connect to the Arduino Cloud. Once connected, we push the variable update for

. You should now see this value updated in the Thing interface in the Arduino Cloud.

Value updated in the Arduino Cloud
Value updated in the Arduino Cloud

You can test out the

variable by creating a dashboard in the Arduino Cloud with a switch widget linked to the variable. Head over to "Dashboards" and create a value widget and a switch widget:

Control the switch from a dashboard.
Control the switch from a dashboard.

When flicking the switch, you should see the following command being printed in the terminal:

1Switch Pressed! Status is <state>

For creating dashboards and linking variables, check out the Dashboard & Widgets documentation.


  • command not found: python
    - encountering this error when running a script indicates that the terminal can't access Python. You can try running
    , as some versions of Python requires this.
  • Connection failed 5, retrying after 1.0s
    - this error is likely due to an invalid device ID or secret key.
  • ModuleNotFoundError: No module named '_m2crypto'
    - likely if you are running an older version of the library. Try updating the library.

Suggested changes

The content on is facilitated through a public GitHub repository. You can read more on how to contribute in the contribution policy.


The Arduino documentation is licensed under the Creative Commons Attribution-Share Alike 4.0 license.