1*********************
2Installation on Linux
3*********************
4
5The following distribution-specific packages are officially supported, and they
6provide an easy way of installing and upgrading Powerline. The packages will
7automatically do most of the configuration.
8
9* `Arch Linux (AUR), Python 2 version <https://aur.archlinux.org/packages/python2-powerline-git/>`_
10* `Arch Linux (AUR), Python 3 version <https://aur.archlinux.org/packages/python-powerline-git/>`_
11* Gentoo Live ebuild in `raiagent <https://github.com/leycec/raiagent>`_ overlay
12* Powerline package is available for Debian starting from Wheezy (via `backports
13  <https://packages.debian.org/wheezy-backports/powerline>`_). Use `search
14  <https://packages.debian.org/search?keywords=powerline&searchon=names&suite=all&section=all>`_
15  to get more information.
16
17If used distribution does not have an official package installation guide below
18should be followed:
19
201. Install Python 3.2+, Python 2.6+ or PyPy and ``pip`` with ``setuptools``.
21   This step is distribution-specific, so no commands provided.
222. Install Powerline using one of the following commands:
23
24   .. code-block:: sh
25
26      pip install --user powerline-status
27
28   will get the latest release version and
29
30   .. code-block:: sh
31
32      pip install --user git+git://github.com/powerline/powerline
33
34   will get the latest development version.
35
36   .. note:: Due to the naming conflict with an unrelated project powerline is
37      named ``powerline-status`` in PyPI.
38
39   .. note::
40      Powerline developers should be aware that``pip install --editable`` does
41      not currently fully work. Installation performed this way are missing
42      ``powerline`` executable that needs to be symlinked. It will be located in
43      ``scripts/powerline``.
44
45Fonts installation
46==================
47
48Fontconfig
49----------
50
51This method only works on Linux. It’s the second recommended method if terminal
52emulator supports it as patching fonts is not needed, and it generally works
53with any coding font.
54
55#. Download the latest version of the symbol font and fontconfig file::
56
57      wget https://github.com/powerline/powerline/raw/develop/font/PowerlineSymbols.otf
58      wget https://github.com/powerline/powerline/raw/develop/font/10-powerline-symbols.conf
59
60#. Move the symbol font to a valid X font path. Valid font paths can be
61   listed with ``xset q``::
62
63      mv PowerlineSymbols.otf ~/.local/share/fonts/
64
65#. Update font cache for the path the font was moved to (root privileges may be
66   needed to update cache for the system-wide paths)::
67
68      fc-cache -vf ~/.local/share/fonts/
69
70#. Install the fontconfig file. For newer versions of fontconfig the config
71   path is ``~/.config/fontconfig/conf.d/``, for older versions it’s
72   ``~/.fonts.conf.d/``::
73
74      mv 10-powerline-symbols.conf ~/.config/fontconfig/conf.d/
75
76If custom symbols still cannot be seen then try closing all instances of the
77terminal emulator. Restarting X may be needed for the changes to take effect.
78
79If custom symbols *still* can’t be seen, double-check that the font have been
80installed to a valid X font path, and that the fontconfig file was installed to
81a valid fontconfig path. Alternatively try to install a :ref:`patched font
82<installation-patched-fonts>`.
83
84Patched font installation
85-------------------------
86
87This is the preferred method, but it is not always available because not all
88fonts were patched and not all fonts *can* be patched due to licensing issues.
89
90After downloading font the following should be done:
91
92#. Move the patched font to a valid X font path. Valid font paths can be
93   listed with ``xset q``::
94
95      mv 'SomeFont for Powerline.otf' ~/.local/share/fonts/
96
97#. Update font cache for the path the font was moved to (root privileges may be
98   needed for updating font cache for some paths)::
99
100      fc-cache -vf ~/.local/share/fonts/
101
102After installing patched font terminal emulator, GVim or whatever application
103powerline should work with must be configured to use the patched font. The
104correct font usually ends with *for Powerline*.
105
106If custom symbols cannot be seen then try closing all instances of the terminal
107emulator. X server may need to be restarted for the changes to take effect.
108
109If custom symbols *still* can’t be seen then double-check that the font have
110been installed to a valid X font path.
111