Skip to main content
Back to LearnTuyaOpen SDK

Set up your development environment

Install the toolchain TuyaOpen needs, clone the repository, and activate tos.py โ€” the one command you use to configure, build, and flash every project.

Beginner10 minSetup

What you get at the end

A working TuyaOpen checkout on your computer with the tos.py command active in your terminal. Every later learn page โ€” build, flash, pair โ€” assumes you finished this one.

  • tos.py is the single CLI for configuring, building, flashing, and monitoring TuyaOpen projects.
  • Activation creates a Python virtual environment (.venv) inside the repo โ€” it does not touch your system Python.
  • You must re-activate tos.py every time you open a new terminal.

What you need

Before you start, gather the following:

  • A TuyaOpen-compatible development board or module.
  • A USB data cable (a charge-only cable will not work).
  • A computer running Windows, macOS, or Linux.

Install the toolchain

TuyaOpen needs git, Python 3, make, cmake, and ninja. Pick your OS โ€” the install commands and the activate command below both update to match.

Install commands# Ubuntu / Debian (LTS 24 / 22 / 20 recommended) sudo apt-get install lcov cmake-curses-gui build-essential \ ninja-build wget git python3 python3-pip python3-venv \ libc6-i386 libsystemd-dev

Clone TuyaOpen

Clone the repository from GitHub or Gitee (use Gitee if you are in mainland China for a faster clone).

Do not use Chinese characters, spaces, or special characters in the project path. On Windows, do not place the project on the C drive.

# Use GitHub
git clone https://github.com/tuya/TuyaOpen.git

# Or use Gitee
git clone https://gitee.com/tuya-open/TuyaOpen.git

# Enter the project
cd TuyaOpen

If the clone is slow, raise the git HTTP buffer first: git config --global http.postBuffer 524288000.

Activate tos.py

From inside the TuyaOpen directory, run the activate script for your OS. This creates the .venv virtual environment and puts tos.py on your PATH.

You must run the activate command again every time you reopen the terminal.

Activate command. ./export.sh

Verify it worked

Run tos.py version and tos.py check. check validates the tool versions and downloads the SDK submodules on first run.

โฏ tos.py version
[INFO]: Running tos.py ...
[INFO]: v1.3.0

โฏ tos.py check
[INFO]: Running tos.py ...
[INFO]: [git] (2.43.0 >= 2.0.0) is ok.
[INFO]: [cmake] (4.0.2 >= 3.28.0) is ok.
[INFO]: [make] (4.3 >= 3.0.0) is ok.
[INFO]: [ninja] (1.11.1 >= 1.6.0) is ok.
[INFO]: Downloading submodules...
[INFO]: Download submodules successfully.
  • version prints the current tag-commit (e.g. v1.3.0). [Unknown version] means the repo has no tags โ€” common in forks.
  • check confirms git โ‰ฅ 2.0.0, cmake โ‰ฅ 3.28.0, make โ‰ฅ 3.0.0, ninja โ‰ฅ 1.6.0, then runs git submodule update --init.
  • When you are done for the day, run deactivate (Linux/Mac) or exit (Windows) to leave the virtual environment.

Troubleshooting

Activation of tos.py fails on Linux

Usually python3-venv is missing. Install it and retry: sudo apt-get install python3-venv. If activation still fails, delete the ./.venv directory and activate again.

tos.py check reports a tool version too low

Install or upgrade the named tool to at least the minimum version shown (git 2.0.0, cmake 3.28.0, make 3.0.0, ninja 1.6.0), then run tos.py check again.

Submodule download fails during check

Run it manually in the repo root: git submodule update --init, then re-run tos.py check.

On Windows, arrow keys do not work in `tos.py config menu`

Terminal emulator compatibility. Use cmd or PowerShell, or navigate with h j k l (left/down/up/right).

Next: build your first firmware โ†’Full environment docs โ†’tos.py command reference โ†’