This is the documentation for the latest (master) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Troubleshooting West

This page covers common issues with west and how to solve them.

“Error: unexpected keyword argument ‘requires_workspace’”

This error occurs on some Linux distributions after upgrading to west 0.7.0 or later from 0.6.x. For example:

$ west update
[... stack trace ...]
TypeError: __init__() got an unexpected keyword argument 'requires_workspace'

This appears to be a problem with the distribution’s pip; see this comment in west issue 373 for details. Some versions of Ubuntu and Linux Mint are known to have this problem. Some users report issues on Fedora as well.

Neither macOS nor Windows users have reported this issue. There have been no reports of this issue on other Linux distributions, like Arch Linux, either.

Workaround 1: remove the old version, then upgrade:

$ pip3 show west | grep Location: | cut -f 2 -d ' '
/home/foo/.local/lib/python3.6/site-packages
$ rm -r /home/foo/.local/lib/python3.6/site-packages/west
$ pip3 install --user west==0.7.0

Workaround 2: install west in a Python virtual environment

One option is to use the venv module that’s part of the Python 3 standard library. Some distributions remove this module from their base Python 3 packages, so you may need to do some additional work to get it installed on your system.

“invalid choice: ‘build’” (or ‘flash’, etc.)

If you see an unexpected error like this when trying to run a Zephyr extension command (like west flash, west build, etc.):

$ west build [...]
west: error: argument <command>: invalid choice: 'build' (choose from 'init', [...])

$ west flash [...]
west: error: argument <command>: invalid choice: 'flash' (choose from 'init', [...])

The most likely cause is that you’re running the command outside of a west workspace. West needs to know where your workspace is to find Extensions.

To fix this, you have two choices:

  1. Run the command from inside a workspace (e.g. the zephyrproject directory you created when you got started).

    For example, create your build directory inside the workspace, or run west flash --build-dir YOUR_BUILD_DIR from inside the workspace.

  2. Set the ZEPHYR_BASE environment variable and re-run the west extension command. If set, west will use ZEPHYR_BASE to find your workspace.

If you’re unsure whether a command is built-in or an extension, run west help from inside your workspace. The output prints extension commands separately, and looks like this for mainline Zephyr:

$ west help

built-in commands for managing git repositories:
  init:                 create a west workspace
  [...]

other built-in commands:
  help:                 get help for west or a command
  [...]

extension commands from project manifest (path: zephyr):
  build:                compile a Zephyr application
  flash:                flash and run a binary on a board
  [...]

“invalid choice: ‘post-init’”

If you see this error when running west init:

west: error: argument <command>: invalid choice: 'post-init'
(choose from 'init', 'update', 'list', 'manifest', 'diff',
'status', 'forall', 'config', 'selfupdate', 'help')

Then you have an old version of west installed, and are trying to use it in a workspace that requires a more recent version.

The easiest way to resolve this issue is to upgrade west and retry as follows:

  1. Install the latest west with the -U option for pip3 install as shown in Installing west.

  2. Back up any contents of zephyrproject/.west/config that you want to save. (If you don’t have any configuration options set, it’s safe to skip this step.)

  3. Completely remove the zephyrproject/.west directory (if you don’t, you will get the “already in a workspace” error message discussed next).

  4. Run west init again.

“already in an installation”

You may see this error when running west init with west 0.6:

FATAL ERROR: already in an installation (<some directory>), aborting

If this is unexpected and you’re really trying to create a new west workspace, then it’s likely that west is using the ZEPHYR_BASE environment variable to locate a workspace elsewhere on your system.

This is intentional; it allows you to put your Zephyr applications in any directory and still use west to build, flash, and debug them, for example.

To resolve this issue, unset ZEPHYR_BASE and try again.