Skip to main content

​
Prerequisites

Before you begin developing with Trezor Suite, you need to install several tools and dependencies.

​
Required Tools

1

Install NVM (Node Version Manager)

Install NVM to manage Node.js versions.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
You can configure your shell to automatically switch Node versions when entering the repository.
2

Install Node.js

The repository requires Node.js 24.11.1 (specified in .nvmrc).
nvm install 24.11.1
nvm use 24.11.1
This version must be consistent with the version defined in suite-native/app/eas.json for mobile builds.
3

Enable Yarn

Enable Yarn package manager through npm. The project uses Yarn 4.12.0.
corepack enable
corepack prepare [email protected] --activate
4

Install Git LFS

Install Git LFS to handle binary assets.
brew install git-lfs
More installation options available in the Git LFS installation guide.

​
Clone the Repository

1

Clone with Git

git clone [email protected]:trezor/trezor-suite.git
cd trezor-suite
2

Initialize Submodules

The repository uses Git submodules for external dependencies.
git submodule update --init --recursive
Enable automatic submodule updates:
git config --global submodule.recurse true
This ensures submodules are updated automatically when pulling changes.
3

Set Up Git LFS

Configure Git LFS for your user account and pull binary assets.
git lfs install
git lfs pull
You only need to run git lfs install once per user account.

​
Install Dependencies

1

Install Node.js Version

Use NVM to install and activate the correct Node.js version.
nvm install
This reads the version from .nvmrc and installs it automatically.
2

Install Node Modules

Install all project dependencies using Yarn.
yarn
If Playwright installation fails, you can skip native builds:
yarn --mode=skip-build
Initial installation can take 5-10 minutes depending on your system and network speed.
3

Build Essential Libraries

Build core libraries required for development.
yarn build:essential
This command builds:
  • @trezor/suite-data - Suite data packages
  • @trezor/transport-bridge - Transport layer
  • Message system configuration
This step takes 3-5 minutes and must complete before running development servers.

​
Platform-Specific Setup

​
macOS and Linux

The development environment is primarily supported on macOS and Linux. No additional setup is required beyond the steps above.

​
Windows

Development on Windows requires additional configuration. Choose one of the following approaches:
1

Install Python

Install Python via the Python for Windows installer.
2

Install Visual Studio

Install Visual Studio Community with C++ build tools.
Required components:
  • Desktop development with C++ workload
  • C++ Clang Tools for Windows
These are needed for node-gyp to build native modules.
3

Install Git for Windows

Install Git for Windows and ensure Git Bash is included.
4

Use Git Bash

All commands must be run in Git Bash, not cmd or PowerShell.If you’ve run yarn in cmd/PowerShell, delete node_modules and start over in Git Bash.
Exclude the trezor-suite folder from Windows Defender to improve build performance.

​
Windows Subsystem for Linux (WSL)

WSL is supported but not actively maintained. Some features may not work as expected.
1

Install WSL2

Install Ubuntu WSL2 (must be version 2).
2

Install Build Tools

In WSL, install required build dependencies:
sudo apt-get install build-essential
3

Install Electron Dependencies

Install Electron dependencies for Linux.
4

Set Up USB Access (Optional)

To connect physical Trezor devices:
  1. Install USBIPD on Windows
  2. Install udev rules in WSL

​
Alternative: Nix Setup

You can use Nix to set up the entire development environment automatically. See the Nix Documentation for details.

​
Using Trezor Emulator

You don’t need a physical Trezor device to develop. Use the Trezor User Env to run emulators for any Trezor model.

​
Verify Installation

Check that everything is set up correctly: 
# Check Node.js version
node --version
# Should output: v24.11.1

# Check Yarn version
yarn --version
# Should output: 4.12.0

# Check Git LFS
git lfs version
# Should output version information

​
Next Steps

Now that your environment is set up:

​
Troubleshooting

​
Yarn Installation Fails

If yarn fails during installation:
  1. Try installing with yarn --mode=skip-build
  2. Delete node_modules and run yarn again
  3. Ensure you’re using the correct Node.js version (nvm use)

​
Build Times

Expected build times:
  • Initial setup: 15-20 minutes
  • Full library builds: 10-15 minutes
  • Essential builds: 3-5 minutes

​
Submodule Issues

If submodules are out of sync: 
git submodule update --init --recursive --force

​
Git LFS Issues

If binary assets are missing: 
git lfs fetch --all
git lfs pull

Build docs developers (and LLMs) love

Get started for freeTalk to us