AWS IoT Device SDK for Python: MQTT and device shadow access

The v1 SDK is in maintenance, not development

The first thing in the README is a notice that a new AWS IoT Device SDK is now available, in the awslabs repository under the name aws-iot-device-sdk-python-v2, described as a complete rework built to improve reliability, performance and security, with an invitation for feedback. The line under it sets the status of the repository you are reading: this SDK will no longer receive feature updates, but it will receive security updates. That is the single most important fact for anyone evaluating it, and it should shape the decision before any feature is looked at. A device fleet that already runs on this SDK has a supported path for security fixes, which is a genuine benefit, but a new project should look at the v2 rewrite first and treat this one as the older generation. The release history shows the same pattern, with v1.6.2 published on 2026-10-01 and titled for a fix to TLS hostname verification, v1.6.1 on 2026-07-24 and v1.6.0 on 2026-01-28.

Three ways to reach the broker

The SDK is built on top of a modified Paho MQTT Python client library, and the documentation lists three connection types. The first is MQTT over TLS 1.2 with X.509 certificate based mutual authentication. The second is MQTT over the WebSocket protocol with AWS Signature Version 4 authentication. The third is MQTT over TLS 1.2 with X.509 mutual authentication plus the TLS ALPN extension. The ports follow from the choice: MQTT over TLS uses port 8883 and port 443, and the WebSocket protocol also uses port 443. Authentication follows as well, with a valid certificate and private key required for the certificate based connections, and a valid IAM access key ID and secret access key pair required for the WebSocket path. The device shadow is the other half of the value proposition. A shadow is a JSON document holding current state for a thing, and it can be created and maintained for each device so that its state can be read and set whether or not the device is currently connected to the Internet.

Installing from pip or from the source tree

The requirement is Python 3.8 or newer, and the documentation is candid that the SDK worked with older versions in the past but they are no longer formally supported, with the expectation that the minimum version will loosely track the minimum non-end-of-life version over time. Installation from pip is a single command:

    pip install AWSIoTPythonSDK

Building from source clones the repository and runs the setup script:

    git clone https://github.com/aws/aws-iot-device-sdk-python.git
    cd aws-iot-device-sdk-python
    python setup.py install

A zip archive is also published on S3, and the documentation gives the same install command for the unpacked package. The package metadata in setup.py names the distribution AWSIoTPythonSDK, describes it as an SDK for connecting to AWS IoT using Python, and classifies it under the Apache Software License with a development status of Mature. The top level of the repository carries the `AWSIoTPythonSDK/` package, a `samples/` directory, a `test/` and `test-integration/` pair, and a `continuous-delivery/` directory, which is the usual shape for a library that has to run against a live broker in integration tests.

Shadow clients, jobs and the sample set

The SDK implements the shadow protocol so applications can retrieve, update and delete shadow documents, and it allows operations on shadow documents of a single or multiple shadow instances in one MQTT connection. The same connection can carry shadow operations and ordinary publish and subscribe traffic, which is the detail that makes it usable on a constrained device, since opening a second connection is often the expensive part. The sample directories in the repository map onto the feature areas: `basicPubSub`, `basicShadow`, `ThingShadowEcho`, `jobs` and `greengrass`. The jobs sample corresponds to the `AWSIoTPythonSDK.core.jobs` package listed in the setup metadata, alongside `core.shadow`, `core.protocol`, `core.protocol.paho`, `core.protocol.internal`, `core.protocol.connection`, `core.greengrass` and `core.greengrass.discovery`, and an `exception` package. The greengrass packages and the discovery subpackage are what carry the local discovery and shadow behaviour for Greengrass deployments.

Credentials by certificate or by SigV4

The credential story follows the connection type, and the SDK offers two ways to supply IAM credentials. The first is a method call, and the SDK checks for it before anything else:

    python setup.py install

The documentation advises against hard-coding credentials in a custom script and points at Amazon Cognito Identity or another credential provider instead. The second route is environment variables, which the SDK checks when no custom configuration was made, with `AWS_ACCESS_KEY_ID` for the access key, `AWS_SECRET_ACCESS_KEY` for the secret key, and `AWS_SESSION_TOKEN`, which is required only when using temporary credentials. For the certificate based path you download the AWS IoT root CA, use the AWS IoT console to create and download the certificate and private key, and specify the location of those files when you initialise the client. Note that both paths require the root CA, since SigV4 over WebSocket is still TLS.

Usage metrics are on unless you turn them off

Since release v1.3.0 the SDK collects usage metrics indicating which language and version of the SDK is being used. The documentation states that the feature is enabled by default, that it allows prioritising resources towards addressing issues faster in the SDKs that see the most, and that it is an important data point for that purpose. It also says plainly that not all customers want to report this data, and that the sending of usage metrics can be disabled with a corresponding API on either client class:

    # AWS IoT MQTT Client
    AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTClient.enableMetricsCollection()
    AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTClient.disableMetricsCollection()
    # AWS IoT MQTT Shadow Client
    AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTShadowClient.enableMetricsCollection()
    AWSIoTPythonSDK.MQTTLib.AWSIoTMQTTShadowClient.disableMetricsCollection()

This is worth a moment of attention in a device fleet, because a device that is deployed rather than tested is exactly the case where the default matters. The calls are static methods on the client classes, so the decision is a one line change at startup rather than a configuration problem, and it is better to make it deliberately than to inherit the default.

What this SDK is for, and what it is not

The scope is deliberately narrow, and that is a strength on a device. By connecting a device to AWS IoT, the SDK gives it secure access to the message broker, to rules and to the device shadow, and through those to services such as AWS Lambda, Amazon Kinesis and Amazon S3. It is not a general AWS client, and it only implements the device half of that conversation. The comparison that matters is with the v2 SDK, not with another MQTT library, since the choice on the table is which generation of the same SDK to build on. The v1 route gives you a mature, Apache 2.0 licensed library with a documented shadow and jobs client, a working WebSocket path for devices that cannot be given X.509 certificates, and the ability to turn off telemetry. The v2 route gives you a rewrite that the maintainers describe as better on reliability, performance and security, and that is where new device work belongs.

Editorial conclusion

The v1 SDK still works for existing deployments and its shadow and jobs clients remain well documented, but you should start new work on the v2 rewrite rather than on this repository, since feature development here has stopped. It is the right choice only if you have an existing Python device fleet on v1 and want security patches without a port. Before you build on it, confirm your Python version, since the supported floor is 3.8 and older versions are no longer formally supported, and read the section on usage metrics, which are on by default and can be disabled. The last push was on 2026-10-01 with v1.6.2 published the same day, a release whose title is the fix for TLS hostname verification.

Frequently asked questions

Official sources

1. aws/aws-iot-device-sdk-python on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases