1************
2Installation
3************
4
5Generic requirements
6====================
7
8* Python 2.6 or later, 3.2 or later, PyPy 2.0 or later, PyPy3 2.3 or later. It
9  is the only non-optional requirement.
10
11  .. warning:
12     It is highly advised to use UCS-4 version of Python because UCS-2 version
13     uses significantly slower text processing (length determination and
14     non-printable character replacement) functions due to the need of
15     supporting unicode characters above U+FFFF which are represented as
16     surrogate pairs. This price will be paid even if configuration has no such
17     characters.
18
19* C compiler. Required to build powerline client on linux. If it is not present
20  then powerline will fall back to shell script or python client.
21* ``socat`` program. Required for shell variant of client which runs a bit
22  faster than python version of the client, but still slower than C version.
23* ``psutil`` python package. Required for some segments like cpu_percent. Some
24  segments have linux-only fallbacks for ``psutil`` functionality.
25* ``hglib`` python package *and* mercurial executable. Required to work with
26  mercurial repositories.
27* ``pygit2`` python package or ``git`` executable. Required to work with ``git``
28  repositories.
29* ``bzr`` python package (note: *not* standalone executable). Required to work
30  with bazaar repositories.
31* ``pyuv`` python package. Required for :ref:`libuv-based watcher
32  <config-common-watcher>` to work.
33* ``i3ipc`` python package. Required for i3wm bindings and segments.
34* ``xrandr`` program. Required for the multi-monitor lemonbar binding and the
35  :py:func:`powerline.listers.i3wm.output_lister`.
36
37.. note::
38    Until bazaar supports Python-3 or PyPy powerline will not support
39    repository information when running in these interpreters.
40
41.. _repository-root:
42
43.. note::
44   When using ``pip``, the ``{repository_root}`` directory referenced in
45   documentation may be found using ``pip show powerline-status``. In the output
46   of ``pip show`` there is a line like ``Location: {path}``, that ``{path}`` is
47   ``{repository_root}``. Unless it is ``--editable`` installation this is only
48   applicable for ``{repository_root}/powerline/…`` paths: something like
49   ``{repository_root}/scripts/powerline-render`` is not present.
50
51   When using other packages referenced paths may not exist, in this case refer
52   to package documentation.
53
54Pip installation
55================
56
57Due to a naming conflict with an unrelated project powerline is available on
58PyPI under the ``powerline-status`` name:
59
60.. code-block:: sh
61
62    pip install powerline-status
63
64is the preferred method because this will get the latest release. To get current
65development version
66
67.. code-block:: sh
68
69    pip install --user git+git://github.com/powerline/powerline
70
71may be used. If powerline was already checked out into some directory
72
73.. code-block:: sh
74
75    pip install --user --editable={path_to_powerline}
76
77is useful, but note that in this case ``pip`` will not install ``powerline``
78executable and something like
79
80.. code-block:: sh
81
82    ln -s {path_to_powerline}/scripts/powerline ~/.local/bin
83
84will have to be done (:file:`~/.local/bin` should be replaced with some path
85present in ``$PATH``).
86
87.. note::
88    If ISP blocks git protocol for some reason github also provides ``ssh``
89    (``git+ssh://git@github.com/powerline/powerline``) and ``https``
90    (``git+https://github.com/powerline/powerline``) protocols. ``git`` protocol
91    should be the fastest, but least secure one though.
92
93Fonts installation
94==================
95
96Powerline uses several special glyphs to get the arrow effect and some custom
97symbols for developers. This requires having either a symbol font or a patched
98font installed in the system. The used application (e.g. terminal emulator) must
99also either be configured to use patched fonts (in some cases even support it
100because custom glyphs live in private use area which some applications reserve
101for themselves) or support fontconfig for powerline to work properly with
102powerline-specific glyphs.
103
104:ref:`24-bit color support <config-common-term_truecolor>` may be enabled if
105used terminal emulator supports it (see :ref:`the terminal emulator support
106matrix <usage-terminal-emulators>`).
107
108There are basically two ways to get powerline glyphs displayed: use
109:file:`PowerlineSymbols.otf` font as a fallback for one of the existing fonts or
110install a patched font.
111
112.. _installation-patched-fonts:
113
114Patched fonts
115-------------
116
117This method is the fallback method and works for every terminal.
118
119Download the font from `powerline-fonts`_. If preferred font can’t be found in
120the `powerline-fonts`_ repo, then patching the preferred font is needed instead.
121
122.. _powerline-fonts: https://github.com/powerline/fonts
123
124After downloading this font refer to platform-specific instructions.
125
126Installation on various platforms
127=================================
128
129.. toctree::
130
131   Linux <installation/linux>
132   OS X <installation/osx>
133