Installing Python Software¶
This is a guide for end-users on how to easily install Python software on the major platforms. See Packaging Python Software for the related developer guide with distribution methods that enable this painless installation experience.
This is a no-frills version of basic installation procedures for the three major PC platforms. Read the other sections for more details, especially if you encounter any problems with these condensed instructions. Once the basic setup is done, refer to either Installing Releases From PyPI or Installing Directly From GitHub to get an application installed – and in case the project author provides a Python Executable archive, prefer an Installation With PEX.
On Linux, make sure you have the right version of Python pre-installed, and the basic developer toolset available. On Debian-like systems, the following makes sure of that:
sudo apt-get install python python-setuptools python-pkg-resources \ python-virtualenv python-pip python-dev build-essential git
For Python3, replace each occurence of
python3 in the above command –
this requires a fairly recent distribution though, like Debian Jessie.
On Mac OS X, install a modern Python tool chain and missing GNU utilities that are often needed by helper scripts:
sudo easy_install pip && sudo pip install virtualenv brew install coreutils
For Windows, see the Windows (python.org) and Babun (Windows) sections. The former is recommended for users who just want to run some Python software, the latter for developers and ‘power users’ with some existing Python and Linux experience.
There are different ways to get a working Python installation, depending on your computer’s operating system. Note that there are two major versions of Python, and at this time Python 2.7 and Python 3.4 are the recommended versions to use.
Read the documentation of any software you want to install regarding the versions
of Python that particular software runs on, and act accordingly by e.g. calling
virtualenv-3 instead of just
See also these other resources on the web…
POSIX (Linux, BSD, …)¶
On POSIX systems, use whatever package manager your distribution offers, and as the minimum install Python itself and everything to manage Python virtual environments. Usually, the Python interpreter is already installed, but some of the essential extensions and tools might be missing. For Debian-like systems, you need:
apt-get install python python-setuptools python-pkg-resources \ python-virtualenv python-pip
To successfully install C extension packages like
lxml from source into a
you also need the necessary build tools like
On Debian-like systems, this means:
apt-get install python-dev build-essential git
While the new
wheel format for binary distributions can make this unneccessary,
there are practical limitations: wheels have to be built and uploaded to PyPI, which is
seldom the case for every combination of packages and platforms. Also, wheels are not
yet fully supported for POSIX at the time of this writing.
To get the official python.org distribution on Windows, open the Python Releases for Windows page and select the appropriate version. You might want to install both a Python 2 and 3 version, to cover all possible needs of any applications.
It’s also recommended to install the Python Extensions for Windows, because many applications rely on them to access Windows-specific features.
Finally, for Python 2 you should install PyLauncher to be able to start applications distributed as an ‘executbale ZIP’, see its download page. Python 3 already has it pre-installed.
Babun is a turn-key CygWin distribution for developers and is very easy to install and maintain. For a Python developer, Babun allows working in an almost-POSIX environment – with some limitations, of course. This causes less friction when handling FOSS projects that are often biased towards a standard Linux environment, e.g. by using shell scripts for boot-strapping and things like that.
To install it, follow these steps:
Download the installer ZIP archive from the Babun homepage.
Unzip the archive (e.g. using Windows Explorer).
Double-click the installer (
install.bat), and wait…
Catch up (
Change the default shell from
bashif you prefer that (
babun shell /bin/bash).
~/.bashrcto activate loading of
Install additional Python essentials:pact install python-setuptools python-ming pact install libxml2-devel libxslt-devel libyaml-devel curl -skS https://bootstrap.pypa.io/get-pip.py | python pip install virtualenv curl -skS https://raw.githubusercontent.com/mitsuhiko/pipsi/master/get-pipsi.py | python
Conda (Windows, Mac OS X, Linux)¶
Alternatively, there is also the cross-platform, Python-agnostic binary package manager Conda,
with roots in the Scientific Python community and being part of the
Anaconda data processing platform.
Miniconda is a minimal distribution containing only the Conda package manager and Python.
Once Miniconda is installed, you can use the
conda command to install any other packages
and create environments (
conda is the equivalent of
RyRun (Mac OS X, Linux, FreeBSD)¶
Yet another contender is PyRun from eGenix. It is a one file Python runtime, that combines a Python interpreter with an almost complete Python standard library into a single easy-to-use executable of about 12 MiB in size. The selling point is easy installation by only handling a single file, which also results in easy relocation – ideal for using it on an USB stick for portable applications, or part of a self-contained bundle for server installations. It covers all the relevant Python versions (2.6, 2.7, and 3.4), and comes in 32bit and 64bit flavours.
From an application installation standpoint, PyRun allows you to efficiently create isolated runtime environments that include their own Python interpreter and standard library, i.e. are even more detached from the host setup than normal virtualenvs.
Installation With PEX¶
PEX files are Python Executable ZIP files, a format that contains a full distribution of a Python application in a single archive (just like exectable JARs for Java). PEX files can be targeted at a specific platform and Python version, but might also support multiple runtime environments. Consult the documentation of your application for further guidance.
Installing a PEX file is as easy as downloading it from the project’s download page
(e.g. Bintray or the GitHub releases section of a project), using your browser
curl, and then just start it from where you saved it to in your file system.
On Windows, give the file a
which the Python Launcher is registered for.
On POSIX systems,
chmod +x the file to make it executable.
See PEP 441 for a formal description of the underlying mechanics and all the details.
Installing Releases From PyPI¶
For releases published on PyPI, you should use
pip to install them
(i.e. do not use
easy_install anymore). It’s common procedure to
not install into
/usr/local on Linux, but instead create a so-called
virtualenv, which is a runtime environment that is (by default) isolated
against the host system and its packages, as well as against other virtualenvs.
This means that you don’t have to carefully manage version numbers, you can
pip install exactly those versions an application works best with.
To create a virtualenv, go to the desired install location, and create the new environment, also giving it a name:
cd ~/.local/virtualenvs virtualenv ‹newenv› . ‹newenv›/bin/activate pip install -UI pip setuptools # get newest tooling
The third command activates the virtualenv, which means that
when you call
pip, they run in the context of
Now all you have to do is call
pip install ‹my-new-app› and
it’ll get installed into that environment. If the package provides
command line tools, don’t forget to add the
bin directory to
PATH – or better yet symlink those commands into your
~/bin directory or add some definitions to
to make them selectively available.
If you’re installing a Python package that contains a single command,
then pipsi (Python Script Installer) allows installing and updating
with a simple one-liner.
pipsi is just a convenient wrapper
virtualenv, and works in POSIX environments
Installing Directly From GitHub¶
In case you really need the freshest source from GitHub,
there are several ways to install a setuptools-enabled project from its repository.
Be aware that this is nothing a casual user should really do,
gain some experience using
pip before trying this.
The following shows different ways to get
pip to download and install the source directly,
with a single command.
Via a ZIP archive download (does not need
gitinstalled):pip install "https://github.com/‹USER›/‹REPO-NAME›/archive/‹TAG-OR-SHA›.zip"
develop– in the GitHub web UI, you can use the
branchselector above the file listing to first select a branch, then the
Download ZIPbutton at the bottom of the sidebar gives you the neccessary link.
git clone:pip install "git+https://github.com/‹USER›/‹REPO-NAME›.git"
git clonewith a tag or hash:pip install "git+https://github.com/‹USER›/‹REPO-NAME›.git@‹TAG-OR-SHA›"
From a working directory you manually cloned into your file system:pip install "‹working-directory-path›"
The forms that use
gitdirectory can also be done as an editable package – the difference is that the package will end up in a top-level
srcdirectory instead of the deeply nested
…/site-packagesone, and any changes to the source will be instantly visible to any process that imports it. When you plan to change the source or otherwise need quick access to it, that makes this easy:pip install -e "git+….git#egg=‹PKG-NAME›"
Note that all these forms work in requirements files,
which in the end are only lists of
pip install arguments.