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.
A warning to readers of the HTML version of this manual: all options below are preceded with with TWO dashes and no intervening space between the dashes (e.g. Dash-Dash-home). The default HTML conversion tools mangle these into a single dash.
For RPM based systems, simply install the supplied package in the usual manner. If you download the tar archive, the process is:
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 [Again, in the HTML manual, the option is called - -install=scripts, with TWO dashes and no intervening space between the dashes]:
$ 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).
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
At this point I don't know of such a released version for OSX 10.4 (Tiger), or if the problem even occurs with Tiger at all (feedback welcome).
Users installing against fink's Python or a properly hand-built one should not have this problem.
While you can use IPython under Windows with only a stock Python installation, there is one extension, readline, which will make the whole experience a lot more pleasant. It is almost a requirement, since IPython will complain in its absence (though it will function).
The readline extension needs two other libraries to work, so in all you need:
Some of IPython's very useful features are:
You can find Gary's tools at http://sourceforge.net/projects/uncpythontools; Gary's readline requires in turn the ctypes library by Thomas Heller, available at http://starship.python.net/crew/theller/ctypes, and Mark Hammond's PyWin32 from http://starship.python.net/crew/mhammond(PyWin32 is great for anything Windows-related anyway, so you might as well get it).
Under MS Windows, IPython will complain if it can not find this readline library at startup and any time the %colors command is issued, so you can consider it to be a quasi-requirement.
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.
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.
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.
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.