Installation

Using pip:

pip3 install west-rs

(Use pip3 uninstall west-rs to uninstall it.)

The distribution is named west-rs, but it is a drop-in replacement for the v1 west package: it provides the same west command and the same west Python package. Uninstall v1 first (pip3 uninstall west); the two cannot coexist in one environment because they ship the same files.

The wheel contains the west binary, which pip places on your PATH, and the Python package. One abi3 wheel covers every supported Python version (3.10 and newer). When no prebuilt wheel matches your platform, pip builds from the source distribution, which requires a Rust toolchain (see Prerequisites).

Other ways to install:

• uv tool install west-rs installs the same wheel into an isolated environment managed by uv. Extension commands run in a separate interpreter (see below), so point WEST_PYTHON at that environment’s Python, for example ~/.local/share/uv/tools/west-rs/bin/python, or install west into the virtual environment you use for Zephyr instead.

• cargo install --path crates/west-cli from a checkout builds only the west binary, with no Python dependency at all. All built-in commands work.

Extension commands (west build, west flash, …) are Python programs. The binary runs them with the interpreter named by WEST_PYTHON, else the active virtual environment’s Python, else python3 on PATH, and that interpreter needs the west Python package installed.

Basic Usage

West lets you manage multiple Git repositories under a single directory using a single file, called the west manifest file, or manifest for short. By default the manifest file is named west.yml. You use west init to set up this directory, then west update to fetch and/or update the repositories named in the manifest.

Example usage with upstream Zephyr’s manifest file:

mkdir zephyrproject && cd zephyrproject
west init -u https://github.com/zephyrproject-rtos/zephyr
west update

What just happened:

• west init clones the west manifest repository given with -u, in this case the zephyr repository, into the workspace. The manifest repository contains west.yml, a YAML description of the Zephyr installation, including Git repositories and other metadata. West records the workspace state in a .west/ directory next to it.

• west update clones the other repositories named in the manifest file, creating working trees in the workspace directory zephyrproject. Projects are fetched in parallel by default; use -j 1 or --raw to see each Git command’s native output in sequence.

There is no default manifest URL: -u (or its v1 spelling -m) is required unless you initialize from an existing local manifest repository with west init -l. Use --revision (--mr) to pick a revision of the manifest repository; if not given, the remote’s default branch is used. Use --manifest-file (--mf) to use a manifest file other than west.yml.

West doesn’t care if the manifest repository is zephyr or not. You can and are encouraged to make your own manifest repositories to meet your needs. Manifest files may be written in YAML, TOML, or JSON; the format is chosen by file extension.

For more details, see West (Zephyr’s meta-tool) in the Zephyr documentation.

Commands

West has multiple sub-commands. After running west init, you can run them from anywhere under the workspace. The built-in commands are:

west -h lists the built-in commands. west help additionally lists the extension commands and aliases available in the current workspace. Get help on any command with west <command> -h; west <command> --help prints the longer form.

Commands that touch every project (update, diff, status, compare, forall, grep) run in parallel by default and accept -j N to control the number of jobs. They write command data to stdout and everything else (per-project banners, progress bars, summaries, warnings) to stderr, so redirecting stdout yields clean, machine-readable output.

West is extensible: you can add new commands to west without modifying its source code. Extension commands are Python classes declared in a west-commands file (YAML, TOML, or JSON) inside a project. The Rust binary discovers them and runs each one through the west Python package. See Extensions in the documentation for details.

Configuration

West follows Git-like conventions for configuration: a system file, a per-user global file, and a per-workspace local file at .west/config.toml, with local values taking precedence. Configuration files are TOML and keys are dotted, for example manifest.path or tool.git.fetch.strategy.

west config list
west config get manifest.path
west config set --global update.jobs 4
west config unset update.jobs

Any command accepts one-off overrides with -c NAME=VALUE and extra files with --config-file PATH.

Migrating from west v1

West v2 keeps the manifest format, the workspace layout, the Python extension command API, and the names and meanings of nearly all command-line options. The changes you are most likely to notice are:

• Configuration files are TOML rather than INI. west config migrate converts an existing v1 configuration file to v2 TOML at the same scope and leaves the original in place.

• west config takes an explicit subcommand (get, set, unset, list, migrate) instead of positional arguments.

• Diagnostics are prefixed west: error: and west: warning:. Exit codes are 0 (success), 1 (failure), and 2 (usage error or unmet pre-condition, such as naming an uncloned project).

• west -h shows built-ins only; west help shows extensions and aliases.

• west selfupdate is gone. Upgrade through the package manager you installed west with.

MIGRATION.md in this repository lists every known difference, including Python API changes, with each entry tagged as changed, dropped, or still a gap.

Hacking on West

This section contains notes for getting started developing west itself.

# Using uv
uv sync --frozen

# Using pip, in an active virtual environment
pip3 install --group dev

cargo build --release -p west-cli --bin west

uv run poe build

pip3 install -e .

cargo test --workspace

# Full check: tests, ruff lint, ruff format, mypy
uv run poe all

# Just the pytest suite
uv run poe test

# In parallel with pytest-xdist
uv run poe test-xdist

# One file
uv run poe test tests/test_manifest.py

# One test
uv run poe test tests/test_config.py::test_config_global

# Tests matching a keyword, without output capture
uv run poe test -k import --capture=no

uv run poe lint
uv run poe format
uv run poe types

uv build

pip3 install -U dist/west_rs-*.whl

scripts/build-wheels.sh --platform macos
scripts/build-wheels.sh --platform linux      # needs docker
scripts/build-wheels.sh --only cp310-manylinux_x86_64   # a single wheel

pip3 uninstall west-rs
# Pull request 830
pip3 install https://github.com/zephyrproject-rtos/west/archive/pull/830/head.zip
# Someone's random version
pip3 install https://github.com/someone_you_trust/west/archive/some_branch_or_tag.zip