diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 8b859d19..8e46b39c 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -40,28 +40,35 @@ Generic requirements
 Pip installation
 ================
 
-This project is currently unavailable from PyPI due to a naming conflict with an 
-unrelated project, thus you will have to use the following command to install 
-powerline with ``pip``:
+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 you the latest release. To get 
+current development version
 
 .. code-block:: sh
 
     pip install --user git+git://github.com/powerline/powerline
 
-. You may also choose to clone powerline repository somewhere and use
+may be used. If powerline was already checked out into some directory
 
 .. code-block:: sh
 
     pip install --user --editable={path_to_powerline}
 
-, but note that in this case ``pip`` will not install ``powerline`` executable 
-and you will have to do something like
+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
 
-(:file:`~/.local/bin` should be replaced with some path present in ``$PATH``).
+will have to be done (:file:`~/.local/bin` should be replaced with some path 
+present in ``$PATH``).
 
 .. note::
     If your ISP blocks git protocol for some reason github also provides ``ssh`` 
@@ -69,12 +76,6 @@ and you will have to do something like
     (``git+https://github.com/powerline/powerline``) protocols. ``git`` protocol 
     should be the fastest, but least secure one though.
 
-To install release version uploaded to PyPI use
-
-.. code-block:: sh
-
-   pip install powerline-status
-
 Fonts installation
 ==================
 
diff --git a/docs/source/installation/linux.rst b/docs/source/installation/linux.rst
index 7847e8ea..c4ef0f7b 100644
--- a/docs/source/installation/linux.rst
+++ b/docs/source/installation/linux.rst
@@ -19,17 +19,27 @@ follow the installation guide below:
 
 1. Install Python 3.2+ or Python 2.6+ with ``pip``. This step is 
    distribution-specific, so no commands provided.
-2. Install Powerline using the following command::
+2. Install Powerline using one of the following commands:
 
-       pip install --user git+git://github.com/powerline/powerline
+   .. code-block:: sh
 
-.. note:: Due to the naming conflict with an unrelated project powerline is
-   named ``powerline-status`` in PyPI.
+      pip install --user powerline-status
 
-.. note:: If you are powerline developer you should be aware that ``pip install 
-   --editable`` does not currently fully work. If you
-   install powerline this way you will be missing ``powerline`` executable and 
-   need to symlink it. It will be located in ``scripts/powerline``.
+   will get the latest release version and
+
+   .. code-block:: sh
+
+      pip install --user git+git://github.com/powerline/powerline
+
+   will get the latest development version.
+
+   .. note:: Due to the naming conflict with an unrelated project powerline is
+      named ``powerline-status`` in PyPI.
+
+   .. note:: If you are powerline developer you should be aware that ``pip install 
+      --editable`` does not currently fully work. If you
+      install powerline this way you will be missing ``powerline`` executable and 
+      need to symlink it. It will be located in ``scripts/powerline``.
 
 Fonts installation
 ==================
diff --git a/docs/source/installation/osx.rst b/docs/source/installation/osx.rst
index 4866cb3c..7e89ed4d 100644
--- a/docs/source/installation/osx.rst
+++ b/docs/source/installation/osx.rst
@@ -22,10 +22,20 @@ Python package
       should also install GNU env named ``genv``. This may be achieved by 
       running ``brew install coreutils``.
 
-2. Install Powerline using the following command::
+2. Install Powerline using one of the following commans:
+
+   .. code-block:: sh
+
+       pip install --user powerline-status
+
+   will get current release version and
+
+   .. code-block:: sh
 
        pip install --user git+git://github.com/powerline/powerline
 
+   will get latest development version.
+
    .. warning::
       When using ``brew install`` to install Python one must not supply
       ``--user`` flag to ``pip``.
@@ -37,8 +47,8 @@ Python package
    .. note::
       If you are powerline developer you should be aware that ``pip install 
       --editable`` does not currently fully work. If you install powerline this 
-      way you will be missing ``powerline`` executable and need to symlink it. It 
-      will be located in ``scripts/powerline``.
+      way you will be missing ``powerline`` executable and need to symlink it. 
+      It will be located in ``scripts/powerline``.
 
 Vim installation
 ================