Subsections

- Instant instructions
- Detailed Unix instructions (Linux, Mac OS X, etc.)
  - Mac OSX information
  - GUI problems
  - Readline problems
  - DarwinPorts
- Windows instructions
  - Installation procedure
    - Upgrading
    - Manual installation under Win32
- Upgrading from a previous version

#
Installation

## Instant instructions

If you are of the impatient kind, under Linux/Unix simply untar/unzip the download, then install with ``python setup.py install'`. Under Windows, double-click on the provided `.exe` binary installer.

Then, take a look at Sections 3 for configuring things optimally and 4 for quick tips on efficient use of IPython. You can later refer to the rest of the manual for all the gory details.

See the notes in sec. 2.4 for upgrading IPython versions.

## Detailed Unix instructions (Linux, Mac OS X, etc.)

For RPM based systems, simply install the supplied package in the usual manner. If you download the tar archive, the process is:

1. Unzip/untar the `ipython-XXX.tar.gz` file wherever you want (`XXX` is the version number). It will make a directory called `ipython-XXX.` Change into that directory where you will find the files `README` and `setup.py`. `O`nce you've completed the installation, you can safely remove this directory.
2. If you are installing over a previous installation of version 0.2.0 or earlier, first remove your `$HOME/.ipython` directory, since the configuration file format has changed somewhat (the '=' were removed from all option specifications). Or you can call ipython with the `-upgrade` option and it will do this automatically for you.
3. IPython uses distutils, so you can install it by simply typing at the system prompt (don't type the `$`)
   `$ python setup.py install`
   Note that this assumes you have root access to your machine. If you don't have root access or don't want IPython to go in the default python directories, you'll need to use the `--home` option (or `--prefix`). For example:
   `$ python setup.py install --home $HOME/local`
   will install IPython into `$HOME/local` and its subdirectories (creating them if necessary).
   You can type
   `$ python setup.py --help`
   for more details.
   Note that if you change the default location for `--home` at installation, IPython may end up installed at a location which is not part of your `$PYTHONPATH` environment variable. In this case, you'll need to configure this variable to include the actual directory where the `IPython/` directory ended (typically the value you give to `--home` plus `/lib/python`).

### Mac OSX information

Under OSX, there is a choice you need to make. Apple ships its own build of Python, which lives in the core OSX filesystem hierarchy. You can also manually install a separate Python, either purely by hand (typically in `/usr/local`) or by using Fink, which puts everything under `/sw`. Which route to follow is a matter of personal preference, as I've seen users who favor each of the approaches. Here I will simply list the known installation issues under OSX, along with their solutions.

This page: `http://geosci.uchicago.edu/~tobis/pylab.html` contains information on this topic, with additional details on how to make IPython and matplotlib play nicely under OSX.

### GUI problems

The following instructions apply to an install of IPython under OSX from unpacking the `.tar.gz` distribution and installing it for the default Python interpreter shipped by Apple. If you are using a fink install, fink will take care of these details for you, by installing IPython against fink's Python.

IPython offers various forms of support for interacting with graphical applications from the command line, from simple Tk apps (which are in principle always supported by Python) to interactive control of WX, Qt and GTK apps. Under OSX, however, this requires that ipython is installed by calling the special `pythonw` script at installation time, which takes care of coordinating things with Apple's graphical environment.

So when installing under OSX, it is best to use the following command:
`$ sudo pythonw setup.py install --install-scripts=/usr/local/bin`
or
`$ sudo pythonw setup.py install --install-scripts=/usr/bin`
depending on where you like to keep hand-installed executables.

The resulting script will have an appropriate shebang line (the first line in the script whic begins with `#!...`) such that the ipython interpreter can interact with the OS X GUI. If the installed version does not work and has a shebang line that points to, for example, just `/usr/bin/python`, then you might have a stale, cached version in your `build/scripts-<python-version>` directory. Delete that directory and rerun the `setup.py`.

It is also a good idea to use the special flag `--install-scripts` as indicated above, to ensure that the ipython scripts end up in a location which is part of your `$PATH`. Otherwise Apple's Python will put the scripts in an internal directory not available by default at the command line (if you use `/usr/local/bin`, you need to make sure this is in your `$PATH`, which may not be true by default).

### Readline problems

By default, the Python version shipped by Apple does not include the readline library, so central to IPython's behavior. If you install IPython against Apple's Python, you will not have arrow keys, tab completion, etc. For Mac OSX 10.3 (Panther), you can find a prebuilt readline library here:
`http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip`

If you are using OSX 10.4 (Tiger), after installing this package you need to either:

1. move `readline.so` from `/Library/Python/2.3` to `/Library/Python/2.3/site-packages`, or
2. install `http://pythonmac.org/packages/TigerPython23Compat.pkg.zip`

Users installing against Fink's Python or a properly hand-built one should not have this problem.

### DarwinPorts

I report here a message from an OSX user, who suggests an alternative means of using IPython under this operating system with good results. Please let me know of any updates that may be useful for this section. His message is reproduced verbatim below:

> From: Markus Banfi `<markus.banfi-AT-mospheira.net>`

> As a MacOS X (10.4.2) user I prefer to install software using DawinPorts instead of Fink. I had no problems installing ipython with DarwinPorts. It's just:

> `sudo port install py-ipython`

> It automatically resolved all dependencies (python24, readline, py-readline). So far I did not encounter any problems with the DarwinPorts port of ipython.

##
Windows instructions

Some of IPython's very useful features are:

- Integrated readline support (Tab-based file, object and attribute completion, input history across sessions, editable command line, etc.)
- Coloring of prompts, code and tracebacks.

These, by default, are only available under Unix-like operating systems. However, thanks to Gary Bishop's work, Windows XP/2k users can also benefit from them. His readline library originally implemented both GNU readline functionality and color support, so that IPython under Windows XP/2k can be as friendly and powerful as under Unix-like environments.

This library, now named `PyReadline`, has been absorbed by the IPython team (Jörgen Stenarson, in particular), and it continues to be developed with new features, as well as being distributed directly from the IPython site.

The `PyReadline` extension requires `CTypes` and the windows IPython installer needs `PyWin32`, so in all you need:

1. `PyWin32` from `http://starship.python.net/crew/mhammond`.
2. `CTypes` from `http://starship.python.net/crew/theller/ctypes` (you must use version 0.9.1 or newer).
3. `PyReadline` for Windows from `http://projects.scipy.org/ipython/ipython/wiki/PyReadline/Intro`. That page contains further details on using and configuring the system to your liking.

Warning about a broken readline-like library: several users have reported problems stemming from using the pseudo-readline library at `http://newcenturycomputers.net/projects/readline.html`. This is a broken library which, while called readline, only implements an incomplete subset of the readline API. Since it is still called readline, it fools IPython's detection mechanisms and causes unpredictable crashes later. If you wish to use IPython under Windows, you must NOT use this library, which for all purposes is (at least as of version 1.6) terminally broken.

### Installation procedure

Once you have the above installed, from the IPython download directory grab the `ipython-XXX.win32.exe` file, where `XXX` represents the version number. This is a regular windows executable installer, which you can simply double-click to install. It will add an entry for IPython to your Start Menu, as well as registering IPython in the Windows list of applications, so you can later uninstall it from the Control Panel.

IPython tries to install the configuration information in a directory named `.ipython` (`_ipython` under Windows) located in your `home' directory. IPython sets this directory by looking for a `HOME` environment variable; if such a variable does not exist, it uses `HOMEDRIVE\HOMEPATH` (these are always defined by Windows). This typically gives something like `C:\Documents and Settings\YourUserName`, but your local details may vary. In this directory you will find all the files that configure IPython's defaults, and you can put there your profiles and extensions. This directory is automatically added by IPython to `sys.path`, so anything you place there can be found by `import` statements.

#### Upgrading

For an IPython upgrade, you should first uninstall the previous version. This will ensure that all files and directories (such as the documentation) which carry embedded version strings in their names are properly removed.

#### Manual installation under Win32

In case the automatic installer does not work for some reason, you can download the `ipython-XXX.tar.gz` file, which contains the full IPython source distribution (the popular WinZip can read `.tar.gz` files). After uncompressing the archive, you can install it at a command terminal just like any other Python module, by using ``python setup.py install'`.

After the installation, run the supplied `win32_manual_post_install.py` script, which creates the necessary Start Menu shortcuts for you.

##
Upgrading from a previous version

If you are upgrading from a previous version of IPython, after doing the routine installation described above, you should call IPython with the `-upgrade` option the first time you run your new copy. This will automatically update your configuration directory while preserving copies of your old files. You can then later merge back any personal customizations you may have made into the new files. It is a good idea to do this as there may be new options available in the new configuration files which you will not have.

Under Windows, if you don't know how to call python scripts with arguments from a command line, simply delete the old config directory and IPython will make a new one. Win2k and WinXP users will find it in `C:\Documents and Settings\YourUserName\_ipython`, and Win 9x users under `C:\Program Files\IPython\_ipython.`