{"id":6533,"library":"azure-iot-device","title":"Azure IoT Device Library","description":"The Microsoft Azure IoT Device Library provides an easy-to-use API for Python applications to connect to Azure IoT Hub or Azure IoT Edge. It allows devices to send telemetry, receive commands, update device twins, and handle direct methods. The library is actively maintained with frequent releases, currently at version 2.14.0, with release candidates often preceding major updates.","status":"active","version":"2.14.0","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-iot-sdk-python/","tags":["Azure","IoT","device","cloud","MQTT","Edge","telemetry","twin","DPS"],"install":[{"cmd":"pip install azure-iot-device","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"MQTT protocol communication for IoT Hub and Edge. Version 1.x for azure-iot-device 2.14.0; 2.x for upcoming 2.15.0.","package":"paho-mqtt"},{"reason":"Used for Unix domain socket communication, specifically for IoT Edge modules (v2.14.0). Replaced `requests-unixsocket` in 2.14.0, then `requests-unixsocket` returns in 2.15.0rc1.","package":"requests-unixsocket2","optional":true}],"imports":[{"note":"The core client for connecting devices to IoT Hub. Ensure to import from the top-level `azure.iot.device` package, not internal protocol modules.","wrong":"from azure.iot.hub.protocol.iot_hub_device_client import IoTHubDeviceClient","symbol":"IoTHubDeviceClient","correct":"from azure.iot.device import IoTHubDeviceClient"},{"note":"The client for connecting IoT Edge modules. `ModuleClient` was an older naming convention or internal detail.","wrong":"from azure.iot.device import ModuleClient","symbol":"IoTHubModuleClient","correct":"from azure.iot.device import IoTHubModuleClient"},{"note":"Used for device provisioning through Azure Device Provisioning Service (DPS).","symbol":"ProvisioningDeviceClient","correct":"from azure.iot.device import ProvisioningDeviceClient"},{"note":"Represents a message to be sent to Azure IoT Hub or Edge.","symbol":"Message","correct":"from azure.iot.device import Message"}],"quickstart":{"code":"import os\nfrom azure.iot.device import IoTHubDeviceClient, Message\n\n# NOTE: Environment variables are used for security and ease of management.\n# Replace with your actual connection string from Azure IoT Hub device details.\nCONNECTION_STRING = os.environ.get(\"IOTHUB_DEVICE_CONNECTION_STRING\", \"\")\n\ndef main():\n    if not CONNECTION_STRING:\n        print(\"Error: IOTHUB_DEVICE_CONNECTION_STRING environment variable not set.\")\n        print(\"Please set it to your device's connection string.\")\n        exit(1)\n\n    print(\"Connecting to IoT Hub...\")\n    client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)\n    client.connect()\n    print(\"Client connected!\")\n\n    # Send a simple telemetry message\n    telemetry_msg = Message('{\"temperature\": 25.0, \"humidity\": 60.5}')\n    telemetry_msg.content_encoding = \"utf-8\"\n    telemetry_msg.content_type = \"application/json\"\n\n    print(\"Sending message...\")\n    client.send_message(telemetry_msg)\n    print(\"Message sent!\")\n\n    # Disconnect\n    client.shutdown()\n    print(\"Client disconnected.\")\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"This quickstart demonstrates how to connect an Azure IoT Device Client to IoT Hub using a connection string from an environment variable and send a basic JSON telemetry message. Ensure the `IOTHUB_DEVICE_CONNECTION_STRING` environment variable is set with your device's connection string before running."},"warnings":[{"fix":"Upgrade your Python environment to 3.8 or newer. For upcoming `v2.15.0`, Python 3.8 will also be dropped, requiring 3.9+.","message":"Python 3.7 support was dropped in `v2.14.0`. Applications on Python 3.7 must upgrade to 3.8+ or pin `azure-iot-device<2.14.0`.","severity":"breaking","affected_versions":">=2.14.0"},{"fix":"Refer to the release notes for your target version and ensure your Python environment meets the minimum requirements.","message":"Breaking Python version changes are frequent. Python 3.6 was dropped in `v2.13.0`, and 2.7/3.5 in `v2.11.0`. Always check release notes for your Python version.","severity":"breaking","affected_versions":">=2.11.0"},{"fix":"Rely on `pip` to manage sub-dependencies. If experiencing issues, verify the specific `requests-unixsocket` package version installed and check its compatibility with your OS/environment.","message":"Dependency churn for `requests-unixsocket`: `v2.14.0` switched to `requests-unixsocket2` due to the original being abandoned. However, `v2.15.0rc1` indicates a return to the original `requests-unixsocket` after it was updated. This may cause unexpected dependency conflicts or behavior if directly managing sub-dependencies.","severity":"gotcha","affected_versions":"2.14.0, >=2.15.0rc1"},{"fix":"Review the `Paho-MQTT` 2.x release notes if you encounter issues after upgrading to `azure-iot-device >=2.15.0`.","message":"The upcoming `v2.15.0rc1` switches `Paho-MQTT` dependency from 1.x to 2.x. This could introduce breaking changes or require code adjustments if your application directly interacts with `Paho-MQTT` or relies on specific behaviors from version 1.x.","severity":"gotcha","affected_versions":">=2.15.0rc1"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Ensure the 'azure-iot-device' package is installed using `pip install azure-iot-device`. If using a virtual environment, activate it first. If a file is named 'azure.py', rename it to avoid conflicts.","cause":"This error typically occurs when the 'azure-iot-device' package is not installed in the Python environment being used, or there's a conflict with an older 'azure' package that is now deprecated. It can also happen if a user's Python script is named 'azure.py', shadowing the actual 'azure' package.","error":"ModuleNotFoundError: No module named 'azure.iot'"},{"fix":"Verify that the device connection string is correct and has not expired. Regenerate the device key and update the connection string if necessary. Ensure the device is enabled in the Azure IoT Hub portal. Check firewall rules to allow outbound connections on port 8883 (MQTT) or 443 (AMQP over WebSockets). Ensure only one client is using a given device connection string at a time.","cause":"These errors indicate that the device is unable to authenticate with Azure IoT Hub, often due to an incorrect device connection string, an expired Shared Access Signature (SAS) token, a disabled device in IoT Hub, or network/firewall restrictions preventing connection. Using the same device connection string across multiple clients simultaneously can also cause this.","error":"Connection Refused: Not Authorized / Bad Credential / 401003 IoTHubUnauthorized"},{"fix":"Verify the IoT Hub hostname in the connection string is correct and fully qualified (e.g., `your-hub.azure-devices.net`). Check network connectivity and DNS resolution from the device. Ensure that necessary ports (e.g., 8883 for MQTT) are not blocked by a firewall.","cause":"This error often points to a network issue where the device cannot resolve the IoT Hub hostname or establish a connection to it. This can be due to incorrect hostname in the connection string, DNS resolution problems, or network connectivity issues (e.g., no internet access, firewall blocking ports).","error":"ConnectionFailedError / socket.gaierror: [Errno -2] Name or service not known / Could not connect to IoTHub"},{"fix":"When patching reported properties, ensure the request body is correctly formatted as a JSON object containing only the 'reported' properties you intend to update, for example: `{'reported': {'myProperty': 'myValue'}}`. Avoid including 'tags' or 'desired' properties in a patch operation unless you explicitly intend to modify them with their full, correct structure. Verify data types are compatible with IoT Hub twin property limitations (e.g., avoid nested lists in older Edge Agent versions).","cause":"This occurs when attempting to update device twin properties with an incorrectly structured payload, or when using an inappropriate method for updating. Specifically, trying to patch reported properties while implicitly or explicitly setting 'tags' or 'desired' properties to null, or providing invalid data types (e.g., lists where not expected).","error":"Error updating device twin properties / tags and desired properties cannot be null (when patching reported properties)"}]}