{"id":3855,"library":"west","title":"West (Zephyr RTOS Meta-Tool)","description":"West is the Zephyr RTOS project's meta-tool, designed to manage multiple Git repositories under a single directory using a manifest file. It provides commands for initializing workspaces, updating repositories, building, flashing, and debugging Zephyr applications. While primarily a command-line interface tool, `west` also exposes Python APIs for advanced programmatic interaction and extending its functionality. It maintains an active development cycle with frequent releases, often including alpha versions before stable major/minor updates.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/zephyrproject-rtos/west","tags":["Zephyr RTOS","meta-tool","multi-repository","CLI","embedded development","version control"],"install":[{"cmd":"pip install west","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"West manages Git repositories and relies on Git being installed and available in the system's PATH.","package":"git","optional":false},{"reason":"Required for building and flashing Zephyr RTOS applications, though West itself can be used without it for repository management.","package":"Zephyr SDK","optional":true}],"imports":[{"note":"Primarily used for developing custom West extension commands.","symbol":"WestCommand","correct":"from west.commands import WestCommand"},{"note":"Recommended API for reading and managing West's configuration files (system, global, local).","symbol":"Configuration","correct":"from west.configuration import Configuration"},{"note":"Used for programmatic access to the West manifest file structure and its projects.","symbol":"Manifest","correct":"from west.manifest import Manifest"}],"quickstart":{"code":"import subprocess\nimport os\nimport shutil\n\n# Ensure a clean state for the example\nif os.path.exists('zephyrproject'):\n    shutil.rmtree('zephyrproject')\n\ntry:\n    # Initialize a west workspace with the default Zephyr manifest\n    print(\"Initializing west workspace...\")\n    subprocess.run(['west', 'init', 'zephyrproject'], check=True, capture_output=True)\n    print(\"\\nWest workspace initialized in 'zephyrproject'.\")\n\n    # Change into the workspace directory\n    os.chdir('zephyrproject')\n\n    # Update the repositories defined in the manifest\n    print(\"\\nUpdating repositories (this may take some time)...\")\n    subprocess.run(['west', 'update'], check=True, capture_output=True)\n    print(\"\\nRepositories updated successfully.\")\n\n    # List the projects in the workspace\n    print(\"\\nListing projects in the workspace:\")\n    result = subprocess.run(['west', 'list'], check=True, capture_output=True, text=True)\n    print(result.stdout)\n\nexcept subprocess.CalledProcessError as e:\n    print(f\"An error occurred during west command execution: {e}\")\n    print(f\"Stdout: {e.stdout.decode()}\")\n    print(f\"Stderr: {e.stderr.decode()}\")\nexcept FileNotFoundError:\n    print(\"Error: 'west' command not found. Please ensure west is installed and in your PATH.\")\nfinally:\n    # Clean up the created directory for re-runnability\n    os.chdir('..') # Go back up from zephyrproject\n    if os.path.exists('zephyrproject'):\n        shutil.rmtree('zephyrproject')\n        print(\"\\nCleaned up 'zephyrproject' directory.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.9 or higher.","message":"Python 3.8 support was dropped in West v1.3.0. Users must use Python 3.9 or later.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"For 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.","message":"West 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.","severity":"breaking","affected_versions":">=1.0.0 (when used with Zephyr v1.14 LTS)"},{"fix":"Update scripts and commands to use the full, unambiguous argument names. Consult `west <command> --help` for correct options.","message":"Starting 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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"If developing West extensions, migrate from `west.log` functions to the corresponding methods provided by `west.commands.WestCommand` instances.","message":"The `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.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Explicitly 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`.","message":"Since 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`).","severity":"gotcha","affected_versions":">=0.10.1"},{"fix":"If this behavior is undesirable, you can disable it by setting the `update.sync-submodules` configuration option to `false` in your West configuration.","message":"Beginning 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}