Install & Compatibility
Where this runs
tested against v2.14.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.920 runs
installs and imports cleanly · install 0.0s · import 0.871s · 26MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.5s · import 0.800s · 27MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
IoTHubDeviceClient
✓ from azure.iot.device import IoTHubDeviceClient
✗ from azure.iot.hub.protocol.iot_hub_device_client import IoTHubDeviceClient
The core client for connecting devices to IoT Hub. Ensure to import from the top-level `azure.iot.device` package, not internal protocol modules.
IoTHubModuleClient
✓ from azure.iot.device import IoTHubModuleClient
✗ from azure.iot.device import ModuleClient
The client for connecting IoT Edge modules. `ModuleClient` was an older naming convention or internal detail.
ProvisioningDeviceClient
✓ from azure.iot.device import ProvisioningDeviceClient
Used for device provisioning through Azure Device Provisioning Service (DPS).
Message
✓ from azure.iot.device import Message
Represents a message to be sent to Azure IoT Hub or Edge.
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.
import os
from azure.iot.device import IoTHubDeviceClient, Message
# NOTE: Environment variables are used for security and ease of management.
# Replace with your actual connection string from Azure IoT Hub device details.
CONNECTION_STRING = os.environ.get("IOTHUB_DEVICE_CONNECTION_STRING", "")
def main():
if not CONNECTION_STRING:
print("Error: IOTHUB_DEVICE_CONNECTION_STRING environment variable not set.")
print("Please set it to your device's connection string.")
exit(1)
print("Connecting to IoT Hub...")
client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)
client.connect()
print("Client connected!")
# Send a simple telemetry message
telemetry_msg = Message('{"temperature": 25.0, "humidity": 60.5}')
telemetry_msg.content_encoding = "utf-8"
telemetry_msg.content_type = "application/json"
print("Sending message...")
client.send_message(telemetry_msg)
print("Message sent!")
# Disconnect
client.shutdown()
print("Client disconnected.")
if __name__ == "__main__":
main()
Debug
Known issues
breakingPython 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`.fixUpgrade your Python environment to 3.8 or newer. For upcoming `v2.15.0`, Python 3.8 will also be dropped, requiring 3.9+.
affects: >=2.14.0
breakingBreaking 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.fixRefer to the release notes for your target version and ensure your Python environment meets the minimum requirements.
affects: >=2.11.0
gotchaDependency 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.fixRely 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.
affects: 2.14.0, >=2.15.0rc1
gotchaThe 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.fixReview the `Paho-MQTT` 2.x release notes if you encounter issues after upgrading to `azure-iot-device >=2.15.0`.
affects: >=2.15.0rc1
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.iot'
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.
fixEnsure 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.
Connection Refused: Not Authorized / Bad Credential / 401003 IoTHubUnauthorized
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.
fixVerify 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.
ConnectionFailedError / socket.gaierror: [Errno -2] Name or service not known / Could not connect to IoTHub
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).
fixVerify 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.
Error updating device twin properties / tags and desired properties cannot be null (when patching reported properties)
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).
fixWhen 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). Upgrade
Version history
2.14.0latest on PyPI · released Jul 17, 2024
Audit
Dependencies
paho-mqttrequiredMQTT protocol communication for IoT Hub and Edge. Version 1.x for azure-iot-device 2.14.0; 2.x for upcoming 2.15.0.
requests-unixsocket2optionalUsed 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.