next up previous
: Initial configuration... : IPython An enhanced Interactive : Overview



Installation

Instant instructions

If you are of the impatient kind, simply untar/unzip the download, install with `python setup.py install' under Linux/Unix or by double-clicking the setup.py file under Windows, and 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.

Under Unix-type operating systems (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. Once 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 simply by 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. For example:
    $ python setup.py install -home $HOME/local
    will install1 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 - Tk problems under OSX 10.3.5

Users have reported some problems with Tk under OSX (quoting James Boyle from LLNL):

I almost exclusively use ipython in my work. However, I have a problem using ipython and Tk. Using pythonw I can use Tk without any problem.

I can start up using pythonw and perform the actions of the script by hand and get an ipython shell that can be used with Tk. Just using the ipython script and Tk results in the dreaded SetFrontProcess failed, -606.

My question is this - is there anyway to modify the ipython script to enable use of Tk. I would like to keep my usage of ipython consistent across platforms. I have looked at what pythonw does and what the ipython startup does but so far I have not gotten it to work. I am on OSX 10.3.5 and use the Apple python + the Mac Addons + Tk from package manager.
The solution suggested by Bob Ippolito <bob@redivi.com> is to start IPython via pythonw:

pythonw `which ipython`

This can be made into an alias, shown here for tcsh syntax:

alias ipythonw "pythonw `which ipython`"

After this, call ipythonw at the command line.


Under Windows

While you can use IPython under Windows with only a stock Python installation, there are two sets of extensions which will make the whole experience a lot more pleasant. They are almost a requirement, since IPython will complain in their absence (though it will function).

In short, for optimal performance under Windows 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. Readline for Windows from http://sourceforge.net/projects/uncpythontools
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 an incomplete 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.

Mark Hammond's PyWin32

For the automatic installer to work you need Mark Hammond's PyWin32 (formerly PythonWin) extensions. They are great for anything Windows-related anyway, so you might as well get them. If you don't have them, they are located at:

http://starship.python.net/crew/mhammond

Gary Bishop's readline and color support for Windows

Note: this needs PyWin32 to function correctly.

Some of IPython's more powerful features are:

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 implements 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.

You can find Gary's tools at http://sourceforge.net/projects/uncpythontools; note that his readline module requires in turn the ctypes library by Thomas Heller, available at http://starship.python.net/crew/theller/ctypes.

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.

Installation procedeure

Once you have the above installed, from the download directory grab the IPython-XXX.zip file. The popular WinZip handles .tar.gz files perfectly, so use that if you have WinZip and want a smaller download.

Unzip it and double-click on the setup.py file. A text console should open and proceed to install IPython in your system. If all goes well, that's all you need to do. You should now have an IPython entry in your Start Menu with links to IPython and the manuals.

If you don't have PythonWin, you can:

These steps are basically what the auto-installer does for you.

IPython tries to install the configuration information in a directory named .ipython located in your 'home' directory, which it determines by joining the environment variables HOMEDRIVE and HOMEPATH. 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 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.


next up previous
: Initial configuration... : IPython An enhanced Interactive : Overview
Fernando Perez 平成16年12月13日