.. _installing: Installing distributions ------------------------ .. index:: single: Distributions; installing .. _install-locations: Where things are installed ~~~~~~~~~~~~~~~~~~~~~~~~~~ User site and virtual environments .................................. .. index:: single: Installation locations; personal use single: Installation locations; virtual environments By default, ``distil`` installs in the *user site* (see :pep:`370` for more information). This means that you don't need to e.g. use ``sudo`` to install packages for your personal use. If you specify a virtual environment using the ``-e`` flag, installation is done into that environment. System site-packages .................... .. index:: single: Installation locations; system Because of its alpha status, it is not advisable to use ``distil`` to install into a system-wide location. However, ``distil`` does support this if you use the ``--system`` flag when installing, for test purposes. You will typically need administrative privileges (via ``sudo`` on POSIX systems) to do this. Installing new distributions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before installing a distribution, we can check to see what's currently installed (see :ref:`listing` for more information about the ``list`` command):: $ distil -e e2 list pip 1.3.1 Currently, only ``pip`` (and ``setuptools``, which doesn't show up in the list) are installed in this venv. Pure-python distributions ......................... Let's try installing a pure-Python distribution:: $ distil -e e2 install sarge Checking requirements for sarge (0.1) ... done. The following new packages will be downloaded and installed: sarge (0.1) Downloading sarge-0.1.tar.gz to /tmp/tmpG5RzKC 35KB @ 175 KB/s 100 % Done: 00:00:00 Unpacking ... done. Building sarge (0.1) ... Running check ... Running build_ext ... Running build_py ... Build completed. Installing sarge (0.1) ... Running install_headers ... Running install_lib ... Running install_distinfo ... Installation completed. As you can see from the above, ``distil`` employs a set of steps when installing which should be familiar to users of ``distribute`` and ``pip``. However, the implementation is different -- there is no use of command classes, for example. If we again list the installed distributions, we get the expected result:: $ distil -e e2 list sarge 0.1 pip 1.3.1 Bootstrapping pip ................. .. index:: pair: Bootstrapping; pip You can use ``distil`` to bootstrap ``pip``. Let's see it bootstrapping ``pip`` on a vanilla machine which doesn't have ``pip`` installed. First we'll check for ``pip`` being available already:: vinay@nadia-cinnamon ~ $ which pip vinay@nadia-cinnamon ~ $ So, there's no ``pip`` on this machine. I have a :pep:`370` user site set up at ``~/.local``, and it's on my ``PATH``:: vinay@nadia-cinnamon ~ $ echo $PATH /home/vinay/.local/bin:/home/vinay/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games Now let's install ``pip`` using ``distil``:: vinay@nadia-cinnamon ~ $ distil install pip Checking requirements for pip (1.3.1) ... done. The following new packages will be downloaded and installed: pip (1.3.1) Downloading pip-1.3.1.tar.gz to /tmp/tmpSdyftQ 241KB @ 45 KB/s 100 % Done: 00:00:05 Unpacking ... done. Building pip (1.3.1) ... Running check ... Running build_ext ... Running build_py ... Build completed. Installing pip (1.3.1) ... Running install_headers ... Running install_lib ... Running install_scripts ... Running install_distinfo ... Installation completed. vinay@nadia-cinnamon ~ $ which pip /home/vinay/.local/bin/pip vinay@nadia-cinnamon ~ $ pip --version pip 1.3.1 from /home/vinay/.local/lib/python2.7/site-packages (python 2.7) vinay@nadia-cinnamon ~ $ Now, let's install using Python 3.2:: $ distil -p python3.2 install pip Checking requirements for pip (1.3.1) ... done. The following new packages will be downloaded and installed: pip (1.3.1) Downloading pip-1.3.1.tar.gz to /tmp/tmpc6nk63 241KB @ 14 KB/s 100 % Done: 00:00:17 Unpacking ... done. Building pip (1.3.1) ... Running check ... Running build_ext ... Running build_py ... Build completed. Installing pip (1.3.1) ... Running install_headers ... Running install_lib ... Running install_scripts ... Running install_distinfo ... Installation completed. vinay@nadia-cinnamon ~ $ pip --version pip 1.3.1 from /home/vinay/.local/lib/python3.2/site-packages (python 3.2) vinay@nadia-cinnamon ~ $ Distributions which include C extensions ........................................ Let's try installing a distribution which contains a C extension:: $ distil -e e2 install simplejson Checking requirements for simplejson (3.1.0) ... done. The following new packages will be downloaded and installed: simplejson (3.1.0) Downloading simplejson-3.1.0.tar.gz to /tmp/tmp2aRbHT 63KB @ 166 KB/s 100 % Done: 00:00:00 Unpacking ... done. Building simplejson (3.1.0) ... Running check ... Running build_ext ... Building 'simplejson._speedups' extension gcc -pthread -fno-strict-aliasing -DNDEBUG -g -fwrapv -O2 -Wall -Wstrict-prototypes -D_FORTIFY_SOURCE=2 -g -fstack-protector --param=ssp-buffer-size=4 -Wformat -Werror=format-security -fPIC -I/tmp/tmp2aRbHT/simplejson-3.1.0 -I/usr/include/python2.7 -c -o /tmp/tmp2aRbHT/simplejson-3.1.0/build/temp.linux-x86_64-2.7/simplejson/_speedups.o /tmp/tmp2aRbHT/simplejson-3.1.0/simplejson/_speedups.c gcc -pthread -shared -Wl,-O1 -Wl,-Bsymbolic-functions -Wl,-Bsymbolic-functions -Wl,-z,relro /tmp/tmp2aRbHT/simplejson-3.1.0/build/temp.linux-x86_64-2.7/simplejson/_speedups.o -L/tmp/tmp2aRbHT/simplejson-3.1.0/build/temp.linux-x86_64-2.7 -L/usr/lib -o /tmp/tmp2aRbHT/simplejson-3.1.0/build/lib.linux-x86_64-2.7/simplejson/_speedups.so Running build_py ... Build completed. Installing simplejson (3.1.0) ... Running install_headers ... Running install_lib ... Running install_distinfo ... Installation completed. Notice that ``distil`` invoked the C compiler to build ``simplejson``'s C extension. This also works on Windows - simply run the command in a "Visual Studio Command Prompt" window: .. image:: http://i.imgur.com/MiudqKK.png .. _upgrade-existing: Upgrading existing installed distributions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default. ``distil`` only upgrades distributions if you ask it to. To illustrate, let's install a distribution which has a newer version:: $ reuse e2 $ distil -e e2 install "Jinja2 (2.5.5)" Checking requirements for Jinja2 (2.5.5) ... done. The following new packages will be downloaded and installed: Jinja2 (2.5.5) Downloading Jinja2-2.5.5.tar.gz to /tmp/tmpLBegg4 428KB @ 28 KB/s 100 % Done: 00:00:15 Unpacking ... done. Building Jinja2 (2.5.5) ... Running check ... Running build_ext ... Running build_py ... Build completed. Installing Jinja2 (2.5.5) ... Running install_headers ... Running install_lib ... Running install_distinfo ... Installation completed. Now, let's not specify the version:: $ distil -e e2 install Jinja2 Checking requirements for Jinja2 (2.6) ... done. The following installed packages will be upgraded: Jinja2 (2.5.5) -> Jinja2 (2.6) Proceed? (y/n) In this case, ``distil`` assumes you want to upgrade the existing Jinja2 from 2.5.5 to 2.6. If you elect to proceed, the upgrade will be carried out. Instead, let's try installing a distribution which requires Jinja2 and can work with version 2.5.5:: $ distil -e e2 install Flask Checking requirements for Flask (0.9) ... done. The following new packages will be downloaded and installed: Werkzeug (0.8.3) [for Flask] Flask (0.9) Proceed? (y/n) As you can see, ``distil`` only offers to install the additional dependency -- Werkzeug -- and to use the existing Jinja2 installation. If you want to upgrade to the latest version of Jinja2, you can invoke:: $ distil -e e2 install --upgrade Flask Checking requirements for Flask (0.9) ... done. The following new packages will be downloaded and installed: Werkzeug (0.8.3) [for Flask] Flask (0.9) The following installed packages will be upgraded: Jinja2 (2.5.5) -> Jinja2 (2.6) [for Flask] Proceed? (y/n) Now, ``distil`` offers to upgrade Jinja2 to the latest version, as well as downloading and installing Werkzeug. If we confirm that we want to proceed, ``distil`` does the expected thing:: Downloading Werkzeug-0.8.3.tar.gz to /tmp/tmpWZ7TB6 [for Flask] 1082KB @ 56 KB/s 100 % Done: 00:00:19 Unpacking ... done. Downloading Jinja2-2.6.tar.gz to /tmp/tmp1SMzzt [for Flask] 380KB @ 131 KB/s 100 % Done: 00:00:02 Unpacking ... done. Downloading Flask-0.9.tar.gz to /tmp/tmpuhUOcp 470KB @ 52 KB/s 100 % Done: 00:00:09 Unpacking ... done. Building Werkzeug (0.8.3) ... Running check ... Running build_ext ... Running build_py ... Build completed. Building Jinja2 (2.6) ... Running check ... Running build_ext ... Running build_py ... Build completed. Building Flask (0.9) ... Running check ... Running build_ext ... Running build_py ... Build completed. Installing Werkzeug (0.8.3) ... Running install_headers ... Running install_lib ... Running install_distinfo ... Installation completed. Installing Jinja2 (2.6) ... Running install_headers ... Running install_lib ... Running install_distinfo ... Installation completed. Installing Flask (0.9) ... Running install_headers ... Running install_lib ... Running install_distinfo ... Installation completed. Listing the distributions shows the expected results:: $ distil -e e2 list Werkzeug 0.8.3 Flask 0.9 Jinja2 2.6 pip 1.3.1 Dependency handling ~~~~~~~~~~~~~~~~~~~ As you see from the above examples, ``distil`` automatically detects a distribution's dependencies and downloads and installs them, after getting confirmation from the user. (No confirmation is requested if only a single distribution -- the one requested by the user -- would be downloaded and installed.) Installing from wheels ~~~~~~~~~~~~~~~~~~~~~~ .. index:: single: Wheel; installing To install from a wheel, you just specify the path of the wheel when you invoke the ``install`` command:: $ distil -e e2 install /tmp/Flask-0.9-py27-none-any.whl Checking requirements for Flask (0.9) ... done. The following new packages will be downloaded and installed: Jinja2 (2.6) [for Flask] Werkzeug (0.8.3) [for Flask] The following new packages will be installed from a local location: Flask (0.9) Proceed? (y/n) As with distributions installed by name, any dependencies declared in a wheel will be downloaded and installed. See :ref:`binary-dist` for information on how to build wheels. Using requirements files ~~~~~~~~~~~~~~~~~~~~~~~~ As well as specifying individual distributions on the command line, you can also specify requirements files, which have the requirements:: $ cat reqts.txt Flask Sphinx $ distil -e e2 install -r reqts.txt Checking requirements for Flask (0.9) ... done. Checking requirements for Sphinx (1.1.3) ... done. The following new packages will be downloaded and installed: Jinja2 (2.6) [for Sphinx, Flask] Pygments (1.6) [for Sphinx] docutils (0.10) [for Sphinx] Werkzeug (0.8.3) [for Flask] Sphinx (1.1.3) Flask (0.9) Proceed? (y/n) Here is the complete help for ``distil``'s ``install`` command:: $ distil help install usage: distil install [-h] [-y] [-u] [-s] [-r REQTFILE [REQTFILE ...]] [REQT [REQT ...]] Install one or more distributions. positional arguments: REQT A requirement using a distribution on PyPI, or the path of a wheel file. optional arguments: -h, --help show this help message and exit -y, --yes Don't ask for confirmation before installing. -u, --upgrade Upgrade dependencies if possible. The default behaviour is to upgrade dependencies only if necessary. -s, --system Install to system Python (may require sufficient privileges). By default, installations are written to the user site (~/.local), or to a virtual environment specified with -e. -r REQTFILE [REQTFILE ...] Get requirements from specified file(s)