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 combinations of
52platform and shell:
53
54* Linux: bash
55* macOS: bash
56* Windows: not available
57
58In order to enable shell completion, you will need to obtain the corresponding
59completion script and have it sourced every time you enter a new shell session.
60
61To obtain the completion script you can use the ``west completion`` command::
62
63   cd /path/to/zephyr/
64   west completion bash > ~/west-completion.bash
65
66.. note::
67
68   Remember to update your local copy of the completion script using ``west
69   completion`` when you update Zephyr.
70
71Next, you need to import :file:`west-completion.bash` into your bash shell.
72
73On Linux, you have the following options:
74
75* Copy :file:`west-completion.bash` to :file:`/etc/bash_completion.d/`.
76* Copy :file:`west-completion.bash` to
77  :file:`/usr/share/bash-completion/completions/`.
78* Copy :file:`west-completion.bash` to a local folder and source it from your
79  :file:`~/.bashrc`.
80
81On macOS, you have the following options:
82
83* Copy :file:`west-completion.bash` to a local folder and source it from your
84  :file:`~/.bash_profile`
85* Install the ``bash-completion`` package with ``brew``::
86
87    brew install bash-completion
88
89  then source the main bash completion script in your :file:`~/.bash_profile`::
90
91    source /usr/local/etc/profile.d/bash_completion.sh
92
93  and finally copy :file:`west-completion.bash` to
94  :file:`/usr/local/etc/bash_completion.d/`.
95
96.. _PyPI:
97   https://pypi.org/project/west/
98