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
57In order to enable shell completion, you will need to obtain the corresponding
58completion script and have it sourced.
59Using the completion scripts:
60
61.. tabs::
62
63  .. group-tab:: bash
64
65    *One-time setup*:
66
67    .. code-block:: bash
68
69      source <(west completion bash)
70
71    *Permanent setup*:
72
73    .. code-block:: bash
74
75      west completion bash > ~/west-completion.bash; echo "source ~/west-completion.bash" >> ~/.bashrc
76
77  .. group-tab:: zsh
78
79    *One-time setup*:
80
81    .. code-block:: zsh
82
83      source <(west completion zsh)
84
85    *Permanent setup*:
86
87    .. code-block:: zsh
88
89      west completion zsh > "${fpath[1]}/_west"
90
91  .. group-tab:: fish
92
93    *One-time setup*:
94
95    .. code-block:: fish
96
97      west completion fish | source
98
99    *Permanent setup*:
100
101    .. code-block:: fish
102
103      west completion fish > $HOME/.config/fish/completions/west.fish
104
105.. _PyPI:
106   https://pypi.org/project/west/
107