There are two main ways to add Tuya devices to HomeAssistant: the official Tuya integration (cloud-based, the simplest) and Tuya Local (local control, fast response but slightly more involved to configure).
For beginners, the official Tuya integration is strongly recommended. The current version (2025.12.x) has greatly simplified the steps: you no longer need to register a developer account, apply for an Access ID, or worry about the developer trial period expiring. Now you only need a User Code and a QR code scan in the mobile app.
Below is a detailed beginner tutorial based on HomeAssistant 2025.12.2.
Method 1: Official Tuya integration (recommended for beginners)
This method is the simplest. Once configured, every device you can see in the Tuya Smart or Smart Life mobile app will be synced to HomeAssistant automatically.
1. Preparation
- Mobile app: make sure you have the Tuya Smart or Smart Life app installed on your phone.
- Account: you are registered and logged in, and your smart devices (such as plugs and bulbs) have already been added in the app.
- Network: the phone and HomeAssistant should ideally be on the same local network, but this is not mandatory for a cloud integration.
2. Get the User Code
This is the most critical step of the new integration and replaces the complicated developer account used before.
- Open the Tuya Smart or Smart Life app on your phone.
- Tap Me in the bottom right corner.
- Tap the hexagonal settings icon (⚙️) in the top right corner.
- Tap the first item, Account and Security.
- In the middle of the page you will see User Code.
- Tap the copy button next to the code (or write it down manually).
Note
: if you cannot find the User Code, make sure your app has been updated to the latest version.
3. Add the integration in HomeAssistant
- Open the HomeAssistant backend in your computer browser (usually http://homeassistant.local:8123).
- Click Settings in the left sidebar.
- Select Devices & Services.
- Click the blue + ADD INTEGRATION button in the bottom right corner.
- Type Tuya in the search box and click the Tuya icon that appears.
4. Pair the account
- In the window that HomeAssistant pops up, you will be asked to enter the User Code.
- Paste the User Code you just obtained from the mobile app and click Submit.
- A QR code will be displayed on the screen.
- Immediately pick up your phone and open the Tuya/Smart Life app:
- Go back to the app home page (the Home page).
- Tap the + sign in the top right corner and select Scan.
- Scan the QR code on the computer screen.
A confirmation prompt will appear on your phone; tap Confirm Login.
5. Finish
- The HomeAssistant page will refresh automatically and show a success message.
- You can assign the devices to specific rooms (it is recommended to choose an area for easier management), then click Done.
- Now go to the Overview panel and you should see your Tuya devices have appeared and can be switched on and off!
Method 2: Tuya Local (advanced, local control)
If you find the official integration slow to respond, or it stops working when the internet goes down, you can try this solution. It is installed through HACS and can achieve
Brief workflow (for reference):
- HACS (Home Assistant Community Store) must be installed first.
- Search for and download Tuya Local in HACS (note it is not LocalTuya; Tuya Local has friendlier configuration).
- Restart HomeAssistant.
- Add an integration under Devices & Services and search for Tuya Local.
- Advantage of the new version: Tuya Local now also supports the QR code scan mode described above to obtain the Key automatically, so you no longer need to capture traffic on the developer platform. Very convenient.
Frequently asked questions (Q&A)
Q: Older tutorials said you had to register an iot.tuya.com developer account, need an Access ID and Secret, and renew every 6 months. Is that no longer needed? A: No longer needed! That was the old process (before early 2024). The current official integration uses the Smart Home PaaS model, so ordinary users only need to scan a QR code in the app, completely avoiding the tedious developer trial period issue.
Q: What should I do if a device shows as unavailable in HomeAssistant? A:
- Check whether the physical device has power and is connected to the network.
- On the HA integration page, find Tuya, click the three dots, and select Reload.
- If it still does not work, try restarting HomeAssistant.
Q: I renamed a device in the app. Will HA sync it? A: No, it does not sync in real time. You need to go to the Tuya integration page in HA and click Reload, and only then will it update to the latest device name.
