1.. _west-install:
2
3Installing west
4###############
5
6West is written in Python 3 and distributed through `PyPI`_.
7Use :file:`pip3` to install or upgrade west:
8
9On Linux::
10
11  pip3 install --user -U west
12
13On Windows and macOS::
14
15  pip3 install -U west
16
17.. note::
18   See :ref:`python-pip` for additional clarification on using the
19   ``--user`` switch.
20
21Afterwards, you can run ``pip3 show -f west`` for information on where the west
22binary and related files were installed.
23
24Once west is installed, you can use it to :ref:`clone the Zephyr repositories
25<clone-zephyr>`.
26
27.. _west-struct:
28
29Structure
30*********
31
32West's code is distributed via PyPI in a Python package named ``west``.
33This distribution includes a launcher executable, which is also named
34``west`` (or ``west.exe`` on Windows).
35
36When west is installed, the launcher is placed by :file:`pip3` somewhere in
37the user's filesystem (exactly where depends on the operating system, but
38should be on the ``PATH`` :ref:`environment variable <env_vars>`). This
39launcher is the command-line entry point to running both built-in commands
40like ``west init``, ``west update``, along with any extensions discovered
41in the workspace.
42
43In addition to its command-line interface, you can also use west's Python
44APIs directly. See :ref:`west-apis` for details.
45
46.. _west-shell-completion:
47
48Enabling shell completion
49*************************
50
51West currently supports shell completion in the following shells:
52
53* bash
54* zsh
55* fish
56* powershell (board qualifiers only)
57
58In order to enable shell completion, you will need to obtain the corresponding
59completion script and have it sourced.
60Using the completion scripts:
61
62.. tabs::
63
64  .. group-tab:: bash
65
66    *One-time setup*:
67
68    .. code-block:: bash
69
70      source <(west completion bash)
71
72    *Permanent setup*:
73
74    .. code-block:: bash
75
76      west completion bash > ~/west-completion.bash; echo "source ~/west-completion.bash" >> ~/.bashrc
77
78  .. group-tab:: zsh
79
80    *One-time setup*:
81
82    .. code-block:: zsh
83
84      source <(west completion zsh)
85
86    *Permanent setup*:
87
88    .. code-block:: zsh
89
90      west completion zsh > "${fpath[1]}/_west"
91
92  .. group-tab:: fish
93
94    *One-time setup*:
95
96    .. code-block:: fish
97
98      west completion fish | source
99
100    *Permanent setup*:
101
102    .. code-block:: fish
103
104      west completion fish > $HOME/.config/fish/completions/west.fish
105
106  .. group-tab:: powershell
107
108    *One-time setup*:
109
110    .. code-block:: powershell
111
112      west completion powershell | Out-String | Invoke-Expression
113
114    *Permanent setup*:
115
116    .. code-block:: powershell
117
118      Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
119      New-item -type file -force $PROFILE
120      west completion powershell > $HOME/west-completion.ps1
121      (Add-Content -Path $PROFILE -Value ". '{$HOME/west-completion.ps1}'")
122
123.. _PyPI:
124   https://pypi.org/project/west/
125