Install & Compatibility
Where this runs
tested against v1.20.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.95 runs
installs and imports cleanly · install 0.0s · import 0.420s · 39.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.2s · import 0.416s · 40MB
38MB installed
● package 38MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
tinytuya
✓ import tinytuya
Device
✓ from tinytuya import Device
Base class for general Tuya devices
OutletDevice, BulbDevice, Cloud
✓ from tinytuya import OutletDevice, BulbDevice, Cloud
Common device-specific classes and the Cloud API interface
This quickstart demonstrates how to establish local control over a Tuya smart device using TinyTuya. It initializes an `OutletDevice` with device credentials (ID, IP, local key, and protocol version), retrieves its current status, and then toggles the main switch (Data Point 1). Device credentials should ideally be supplied via environment variables or a configuration file. Remember to obtain your device's `LOCAL_KEY` and `DEVICE_ID` using the `tinytuya wizard` CLI tool or the Tuya IoT Platform. [3, 5, 6, 8]
import os
import tinytuya
# --- Configuration (replace with your device details or environment variables) ---
DEVICE_ID = os.environ.get('TUYA_DEVICE_ID', 'YOUR_DEVICE_ID')
DEVICE_IP = os.environ.get('TUYA_DEVICE_IP', 'YOUR_DEVICE_IP') # Can be 'Auto' if devices.json is present
LOCAL_KEY = os.environ.get('TUYA_LOCAL_KEY', 'YOUR_LOCAL_KEY')
DEVICE_VERSION = float(os.environ.get('TUYA_DEVICE_VERSION', '3.3')) # e.g., 3.1, 3.3, 3.5
# --- Local Control Example (OutletDevice) ---
print(f"Connecting to device {DEVICE_ID} at {DEVICE_IP} (version {DEVICE_VERSION})...")
try:
# Initialize the device object
d = tinytuya.OutletDevice(DEVICE_ID, DEVICE_IP, LOCAL_KEY, version=DEVICE_VERSION)
d.set_version(DEVICE_VERSION) # Ensure the correct protocol version is set
# Get current status
data = d.status()
if data and 'dps' in data:
print(f"Device status: {data['dps']}")
# Assuming DP '1' controls the main switch (common for outlets)
current_state = data['dps'].get('1')
print(f"Current switch state (DP 1): {'ON' if current_state else 'OFF'}")
# Toggle the power state
new_state = not current_state
print(f"Setting switch state (DP 1) to: {'ON' if new_state else 'OFF'}")
d.set_status(new_state)
print("Command sent. Waiting for update...")
# Re-check status after a short delay (optional, for verification)
import time
time.sleep(2)
updated_data = d.status()
if updated_data and 'dps' in updated_data:
print(f"Updated switch state (DP 1): {'ON' if updated_data['dps'].get('1') else 'OFF'}")
else:
print("Failed to get device status or 'dps' key not found.")
except Exception as e:
print(f"An error occurred: {e}")
print("Troubleshooting tips:")
print("- Ensure your device ID, IP, and local key are correct.")
print("- Confirm the device is on the same local network as the script.")
print("- Close any official Tuya/Smart Life apps to free the device's TCP connection. [11]")
print("- Check your firewall for UDP (6666, 6667, 7000) and TCP (6668) port access. [3]")
tinytuya --version
Debug
Known issues
breakingStarting with v1.14.0, running the `tinytuya` command-line interface without arguments no longer initiates a scan; it now displays a 'Usage' page. Users must explicitly specify `tinytuya scan` or `python -m tinytuya scan` to discover devices.fixUpdate CLI usage from `tinytuya` to `tinytuya scan` for device discovery.
affects: >=1.14.0
gotchaThe local key for Tuya devices is crucial for local control but will change if the device is re-paired with the Smart Life/Tuya Smart app or removed and re-added. If you encounter decrypt errors or loss of control, you likely need to re-obtain the local key. [1, 3, 10, 11]fixRe-run the `tinytuya wizard` CLI tool or use the Tuya IoT Platform to fetch the updated local key after any device re-pairing or network changes. [5, 6]
affects: All versions
gotchaTuya devices typically allow only one TCP connection at a time for local control. Ensure that official Tuya/Smart Life apps or other smart home integrations (like Home Assistant's native Tuya integration) are completely closed or disconnected from the device before attempting to control it with TinyTuya to avoid connection issues. [1, 10, 11]fixTerminate any other applications or services that might be actively connected to the Tuya device via its local API.
affects: All versions
gotchaSetting up the Tuya IoT Platform project to retrieve local keys often requires subscribing to specific API services (e.g., IoT Core, Authorization, Smart Home Scene Linkage). These services may have trial periods that expire, potentially interrupting your ability to fetch keys or use cloud-dependent features. [1, 5, 8]fixRegularly check your Tuya IoT Platform project's 'Service API' section to ensure required services are active and subscribed. Extend any expiring trial subscriptions if necessary.
affects: All versions (cloud interaction)
gotchaThe `BulbDevice` class underwent significant rewrites and fixes across multiple minor versions (v1.17.0, v1.17.1, v1.17.2). If you are using `BulbDevice` or encounter unexpected behavior with lighting controls, review the changes in these versions, as the expected interaction or internal handling might have evolved.fixReview the `BulbDevice` example usage in the GitHub repository and update your code to align with the latest recommended patterns for lighting control, especially if migrating from older `tinytuya` versions.
affects: 1.17.0-1.17.2
gotchaLocal device discovery and control require specific network ports to be open. UDP ports 6666, 6667, and 7000 are used for discovery, and TCP port 6668 is used for device communication. Firewall rules or network configurations blocking these ports will prevent TinyTuya from functioning correctly. [1, 3, 6, 11, 13]fixEnsure your local network's firewall allows inbound and outbound UDP traffic on ports 6666, 6667, 7000 and TCP traffic on port 6668 from the machine running TinyTuya to your Tuya devices.
affects: All versions (local control)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tinytuya'
The `tinytuya` library has not been installed in your Python environment.
OSError: [Errno 49] Can't assign requested address
The device discovery process failed to bind to a network interface, often due to an invalid or unavailable local IP address for the scanning interface.
fixSpecify your local network interface's IP address using `tinytuya.set_interface("your_local_ip")` or `tinytuya.deviceScan(False, "your_local_ip")`. Timeout waiting for response
The Tuya device did not respond to the communication request within the expected time, possibly due to network issues, incorrect device ID/key, or the device being offline.
fixVerify the device ID and local key, ensure the device is powered on and connected to the same LAN, and check for network isolation (e.g., VLANs) or firewall rules.
ValueError: No JSON object could be decoded
The data received from the Tuya device was not valid JSON, indicating a malformed response or an issue with device communication.
fixRestart the device to clear any communication errors, ensure the device's firmware is compatible, and handle the exception if malformed data is expected from certain devices.
AttributeError: 'OutletDevice' object has no attribute 'set_brightness'
The method `set_brightness` does not exist on the `OutletDevice` object; device-specific control, including brightness, is typically handled via the generic `set_dp()` method.
fixUse `device.set_dp(dp_id, value)` to control specific data points (DPs), where `dp_id` is the relevant data point ID for brightness (e.g., typically `2` for lights) and `value` is the desired brightness.
Upgrade
Version history
1.20.0latest on PyPI · released Jul 6, 2026
Audit
Dependencies
coloramaoptionalOptional for colored console output; gracefully disabled if not present.