Install & Compatibility
Where this runs
tested against v1.5.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.350s · 25.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.2s · import 0.356s · 27MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WestCommand
✓ from west.commands import WestCommand
Primarily used for developing custom West extension commands.
Configuration
✓ from west.configuration import Configuration
Recommended API for reading and managing West's configuration files (system, global, local).
Manifest
✓ from west.manifest import Manifest
Used for programmatic access to the West manifest file structure and its projects.
This quickstart demonstrates how to use `west` from a Python script to initialize and update a Zephyr RTOS workspace. It uses `subprocess` to execute `west` CLI commands, which is the most common way to automate `west` operations in Python. Ensure `git` is installed and available in your system's PATH before running.
import subprocess
import os
import shutil
# Ensure a clean state for the example
if os.path.exists('zephyrproject'):
shutil.rmtree('zephyrproject')
try:
# Initialize a west workspace with the default Zephyr manifest
print("Initializing west workspace...")
subprocess.run(['west', 'init', 'zephyrproject'], check=True, capture_output=True)
print("\nWest workspace initialized in 'zephyrproject'.")
# Change into the workspace directory
os.chdir('zephyrproject')
# Update the repositories defined in the manifest
print("\nUpdating repositories (this may take some time)...")
subprocess.run(['west', 'update'], check=True, capture_output=True)
print("\nRepositories updated successfully.")
# List the projects in the workspace
print("\nListing projects in the workspace:")
result = subprocess.run(['west', 'list'], check=True, capture_output=True, text=True)
print(result.stdout)
except subprocess.CalledProcessError as e:
print(f"An error occurred during west command execution: {e}")
print(f"Stdout: {e.stdout.decode()}")
print(f"Stderr: {e.stderr.decode()}")
except FileNotFoundError:
print("Error: 'west' command not found. Please ensure west is installed and in your PATH.")
finally:
# Clean up the created directory for re-runnability
os.chdir('..') # Go back up from zephyrproject
if os.path.exists('zephyrproject'):
shutil.rmtree('zephyrproject')
print("\nCleaned up 'zephyrproject' directory.")
west --version
Debug
Known issues
breakingPython 3.8 support was dropped in West v1.3.0. Users must use Python 3.9 or later.fixUpgrade your Python environment to version 3.9 or higher.
affects: >=1.3.0
breakingWest v1.0 and later versions are not compatible with Zephyr v1.14 LTS releases. For Zephyr v1.14, West v0.14 or earlier must be used.fixFor Zephyr v1.14 LTS, downgrade west to version 0.14 or earlier (e.g., `pip install west==0.14.0`). For newer Zephyr versions, ensure you are using a compatible west version as specified by the Zephyr documentation.
affects: >=1.0.0 (when used with Zephyr v1.14 LTS)
breakingStarting with West v1.0, abbreviated command-line arguments are no longer accepted (e.g., `--keep-d` for `--keep-descendants`). Full argument names are now required.fixUpdate scripts and commands to use the full, unambiguous argument names. Consult `west <command> --help` for correct options.
affects: >=1.0.0
deprecatedThe `west.log` module is deprecated since West v1.0. `WestCommand` methods like `dbg()`, `inf()`, `wrn()`, `err()` should be used instead for logging output within West extensions.fixIf developing West extensions, migrate from `west.log` functions to the corresponding methods provided by `west.commands.WestCommand` instances.
affects: >=1.0.0
gotchaSince West v0.10.1, `west init --manifest-rev` (`--mr`) no longer defaults to `master`. Instead, it queries the remote repository for its default branch name (e.g., `main`).fixExplicitly specify the revision using `--mr <branch_name>` if your manifest repository's default branch is not the one you intend to use for initialization, or if it changed from `master` to `main`.
affects: >=0.10.1
gotchaBeginning with a certain version (around v1.0), `west update` now synchronizes Git submodules in projects by default. This can cause unexpected behavior if not anticipated.fixIf this behavior is undesirable, you can disable it by setting the `update.sync-submodules` configuration option to `false` in your West configuration.
affects: >=1.0.0
Errors
Common errors & fixes
west: command not found
The 'west' executable is not installed on the system, or its installation directory is not included in the system's PATH environment variable.
fixInstall west using pip: `pip install west` and ensure the Python scripts directory (where west is installed) is added to your system's PATH.
west manifest: Missing required top-level key 'manifest'
The `west.yml` manifest file is missing the mandatory top-level `manifest` key, which defines the structure for projects and groups.
fixCorrect the `west.yml` file to include the `manifest` key, typically followed by `projects:` and other manifest schema elements, e.g., `manifest:
projects:`.
west build: No build directory found. Did you run 'west build' in a workspace subdirectory?
The `west build` command was executed from a directory that is not recognized as part of a west workspace or is not the intended application's root directory within the workspace.
fixNavigate into a Zephyr application directory within your west workspace (where `CMakeLists.txt` resides) before running `west build`.
west: ERROR: failed to clone repository ... (exit code 128)
West failed to clone or fetch a Git repository specified in the manifest, often due to an incorrect repository URL, network connectivity issues, or insufficient authentication/permissions.
fixVerify the repository URL in your `west.yml` file, check your internet connection, and ensure your Git client (and SSH keys/credentials if applicable) are correctly configured for the remote repository.
west init: FATAL: manifest file not found at ...
The `west init` command was executed with a `--mr` (manifest repository) or a direct manifest file path that does not exist or is inaccessible.
fixEnsure the path provided for the manifest file (e.g., `--mr path/to/west.yml`) is correct and that the file exists at that location.
Upgrade
Version history
1.5.0latest on PyPI · released Sep 23, 2025
Audit
Dependencies
gitrequiredWest manages Git repositories and relies on Git being installed and available in the system's PATH.
Zephyr SDKoptionalRequired for building and flashing Zephyr RTOS applications, though West itself can be used without it for repository management.