133 lines
4.9 KiB
ReStructuredText
133 lines
4.9 KiB
ReStructuredText
************
|
||
Installation
|
||
************
|
||
|
||
Generic requirements
|
||
====================
|
||
|
||
* Python 2.6 or later, 3.2 or later, PyPy 2.0 or later, PyPy3 2.3 or later. It
|
||
is the only non-optional requirement.
|
||
|
||
.. warning:
|
||
It is highly advised to use UCS-4 version of Python because UCS-2 version
|
||
uses significantly slower text processing (length determination and
|
||
non-printable character replacement) functions due to the need of
|
||
supporting unicode characters above U+FFFF which are represented as
|
||
surrogate pairs. This price will be paid even if configuration has no such
|
||
characters.
|
||
|
||
* C compiler. Required to build powerline client on linux. If it is not present
|
||
then powerline will fall back to shell script or python client.
|
||
* ``socat`` program. Required for shell variant of client which runs a bit
|
||
faster than python version of the client, but still slower than C version.
|
||
* ``psutil`` python package. Required for some segments like cpu_percent. Some
|
||
segments have linux-only fallbacks for ``psutil`` functionality.
|
||
* ``hglib`` python package *and* mercurial executable. Required to work with
|
||
mercurial repositories.
|
||
* ``pygit2`` python package or ``git`` executable. Required to work with ``git``
|
||
repositories.
|
||
* ``bzr`` python package (note: *not* standalone executable). Required to work
|
||
with bazaar repositories.
|
||
* ``pyuv`` python package. Required for :ref:`libuv-based watcher
|
||
<config-common-watcher>` to work.
|
||
* ``i3ipc`` python package. Required for i3wm bindings and segments.
|
||
* ``xrandr`` program. Required for the multi-monitor lemonbar binding and the
|
||
:py:func:`powerline.listers.i3wm.output_lister`.
|
||
|
||
.. note::
|
||
Until bazaar supports Python-3 or PyPy powerline will not support
|
||
repository information when running in these interpreters.
|
||
|
||
.. _repository-root:
|
||
|
||
.. note::
|
||
When using ``pip`` ``{repository_root}`` directory referenced in
|
||
documentation may be found using ``pip show powerline-status``. In the output
|
||
of ``pip show`` there is a line like ``Location: {path}``, that ``{path}`` is
|
||
``{repository_root}``. Unless it is ``--editable`` installation this is only
|
||
applicable for ``{repository_root}/powerline/…`` paths: something like
|
||
``{repository_root}/scripts/powerline-render`` is not present.
|
||
|
||
When using other packages referenced paths may not exist, in this case refer
|
||
to package documentation.
|
||
|
||
Pip installation
|
||
================
|
||
|
||
Due to a naming conflict with an unrelated project powerline is available on
|
||
PyPI under the ``powerline-status`` name:
|
||
|
||
.. code-block:: sh
|
||
|
||
pip install powerline-status
|
||
|
||
is the preferred method because this will get the latest release. To get current
|
||
development version
|
||
|
||
.. code-block:: sh
|
||
|
||
pip install --user git+git://github.com/powerline/powerline
|
||
|
||
may be used. If powerline was already checked out into some directory
|
||
|
||
.. code-block:: sh
|
||
|
||
pip install --user --editable={path_to_powerline}
|
||
|
||
is useful, but note that in this case ``pip`` will not install ``powerline``
|
||
executable and something like
|
||
|
||
.. code-block:: sh
|
||
|
||
ln -s {path_to_powerline}/scripts/powerline ~/.local/bin
|
||
|
||
will have to be done (:file:`~/.local/bin` should be replaced with some path
|
||
present in ``$PATH``).
|
||
|
||
.. note::
|
||
If ISP blocks git protocol for some reason github also provides ``ssh``
|
||
(``git+ssh://git@github.com/powerline/powerline``) and ``https``
|
||
(``git+https://github.com/powerline/powerline``) protocols. ``git`` protocol
|
||
should be the fastest, but least secure one though.
|
||
|
||
Fonts installation
|
||
==================
|
||
|
||
Powerline uses several special glyphs to get the arrow effect and some custom
|
||
symbols for developers. This requires having either a symbol font or a patched
|
||
font installed in the system. The used application (e.g. terminal emulator) must
|
||
also either be configured to use patched fonts (in some cases even support it
|
||
because custom glyphs live in private use area which some applications reserve
|
||
for themselves) or support fontconfig for powerline to work properly with
|
||
powerline-specific glyphs.
|
||
|
||
:ref:`24-bit color support <config-common-term_truecolor>` may be enabled if
|
||
used terminal emulator supports it (see :ref:`the terminal emulator support
|
||
matrix <usage-terminal-emulators>`).
|
||
|
||
There are basically two ways to get powerline glyphs displayed: use
|
||
:file:`PowerlineSymbols.otf` font as a fallback for one of the existing fonts or
|
||
install a patched font.
|
||
|
||
.. _installation-patched-fonts:
|
||
|
||
Patched fonts
|
||
-------------
|
||
|
||
This method is the fallback method and works for every terminal.
|
||
|
||
Download the font from `powerline-fonts`_. If preferred font can’t be found in
|
||
the `powerline-fonts`_ repo, then patching the preferred font is needed instead.
|
||
|
||
.. _powerline-fonts: https://github.com/powerline/fonts
|
||
|
||
After downloading this font refer to platform-specific instructions.
|
||
|
||
Installation on various platforms
|
||
=================================
|
||
|
||
.. toctree::
|
||
|
||
Linux <installation/linux>
|
||
OS X <installation/osx>
|