Skip to content

Commit 9fc0079

Browse files
ellisonbgellisonbg
committed
Adding missing install.txt.
2 parents 5caf00a + dc83668 commit 9fc0079

File tree

1 file changed

+191
-0
lines changed

1 file changed

+191
-0
lines changed

‎docs/source/install/install.txt

+191
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
Overview
2+
========
3+
4+
This document describes the steps required to install IPython. IPython is organized into a number of subpackages, each of which has its own dependencies. All of the subpackages come with IPython, so you don't need to download and install them separately. However, to use a given subpackage, you will need to install all of its dependencies.
5+
6+
7+
Please let us know if you have problems installing IPython or any of its
8+
dependencies. IPython requires Python version 2.4 or greater. We have not tested
9+
IPython with the upcoming 2.6 or 3.0 versions.
10+
11+
.. warning::
12+
13+
IPython will not work with Python 2.3 or below.
14+
15+
Some of the installation approaches use the :mod:`setuptools` package and its :command:`easy_install` command line program. In many scenarios, this provides the most simple method of installing IPython and its dependencies. It is not required though. More information about :mod:`setuptools` can be found on its website.
16+
17+
More general information about installing Python packages can be found in Python's documentation at http://www.python.org/doc/.
18+
19+
Installing IPython itself
20+
=========================
21+
22+
Given a properly built Python, the basic interactive IPython shell will work with no external dependencies. However, some Python distributions (particularly on Windows and OS X), don't come with a working :mod:`readline` module. The IPython shell will work without :mod:`readline`, but will lack many features that users depend on, such as tab completion and command line editing. See below for details of how to make sure you have a working :mod:`readline`.
23+
24+
Installation using easy_install
25+
-------------------------------
26+
27+
If you have :mod:`setuptools` installed, the easiest way of getting IPython is to simple use :command:`easy_install`::
28+
29+
$ easy_install IPython
30+
31+
That's it.
32+
33+
Installation from source
34+
------------------------
35+
36+
If you don't want to use :command:`easy_install`, or don't have it installed, just grab the latest stable build of IPython from `here <http://ipython.scipy.org/dist/>`_. Then do the following::
37+
38+
$ tar -xzf ipython.tar.gz
39+
$ cd ipython
40+
$ python setup.py install
41+
42+
If you are installing to a location (like ``/usr/local``) that requires higher permissions, you may need to run the last command with :command:`sudo`.
43+
44+
Windows
45+
-------
46+
47+
There are a few caveats for Windows users. The main issue is that a basic ``python setup.py install`` approach won't create ``.bat`` file or Start Menu shortcuts, which most users want. To get an installation with these, there are two choices:
48+
49+
1. Install using :command:`easy_install`.
50+
51+
2. Install using our binary ``.exe`` Windows installer, which can be found at `here <http://ipython.scipy.org/dist/>`_
52+
53+
3. Install from source, but using :mod:`setuptools` (``python setupegg.py install``).
54+
55+
Installing the development version
56+
----------------------------------
57+
58+
It is also possible to install the development version of IPython from our `Bazaar <http://bazaar-vcs.org/>`_ source code
59+
repository. To do this you will need to have Bazaar installed on your system. Then just do::
60+
61+
$ bzr branch lp:ipython
62+
$ cd ipython
63+
$ python setup.py install
64+
65+
Again, this last step on Windows won't create ``.bat`` files or Start Menu shortcuts, so you will have to use one of the other approaches listed above.
66+
67+
Some users want to be able to follow the development branch as it changes. If you have :mod:`setuptools` installed, this is easy. Simply replace the last step by::
68+
69+
$ python setupegg.py develop
70+
71+
This creates links in the right places and installs the command line script to the appropriate places. Then, if you want to update your IPython at any time, just do::
72+
73+
$ bzr pull
74+
75+
Basic optional dependencies
76+
===========================
77+
78+
There are a number of basic optional dependencies that most users will want to get. These are:
79+
80+
* readline (for command line editing, tab completion, etc.)
81+
* nose (to run the IPython test suite)
82+
* pexpect (to use things like irunner)
83+
84+
If you are comfortable installing these things yourself, have at it, otherwise read on for more details.
85+
86+
readline
87+
--------
88+
89+
In principle, all Python distributions should come with a working :mod:`readline` module. But, reality is not quite that simple. There are two common situations where you won't have a working :mod:`readline` module:
90+
91+
* If you are using the built-in Python on Mac OS X.
92+
93+
* If you are running Windows, which doesn't have a :mod:`readline` module.
94+
95+
On OS X, the built-in Python doesn't not have :mod:`readline` because of license issues. Starting with OS X 10.5 (Leopard), Apple's built-in Python has a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9, many of the issues related to the differences between readline and libedit have been resolved. For many users, libedit may be sufficient.
96+
97+
Most users on OS X will want to get the full :mod:`readline` module. To get a working :mod:`readline` module, just do (with :mod:`setuptools` installed)::
98+
99+
$ easy_install readline
100+
101+
.. note:
102+
103+
Other Python distributions on OS X (such as fink, MacPorts and the
104+
official python.org binaries) already have readline installed so
105+
you don't have to do this step.
106+
107+
If needed, the readline egg can be build and installed from source (see the wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
108+
109+
On Windows, you will need the PyReadline module. PyReadline is a separate, Windows only implementation of readline that uses native Windows calls through :mod:`ctypes`. The easiest way of installing PyReadline is you use the binary installer available `here <http://ipython.scipy.org/dist/>`_. The :mod:`ctypes` module, which comes with Python 2.5 and greater, is required by PyReadline. It is available for Python 2.4 at http://python.net/crew/theller/ctypes.
110+
111+
nose
112+
----
113+
114+
To run the IPython test suite you will need the :mod:`nose` package. Nose provides a great way of sniffing out and running all of the IPython tests. The simplest way of getting nose, is to use :command:`easy_install`::
115+
116+
$ easy_install nose
117+
118+
Another way of getting this is to do::
119+
120+
$ easy_install IPython[test]
121+
122+
For more installation options, see the `nose website <http://somethingaboutorange.com/mrl/projects/nose/>`_. Once you have nose installed, you can run IPython's test suite using the iptest command::
123+
124+
$ iptest
125+
126+
127+
pexpect
128+
-------
129+
130+
The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's :command:`irunner` script. On Unix platforms (including OS X), just do::
131+
132+
$ easy_install pexpect
133+
134+
Windows users are out of luck as pexpect does not run there.
135+
136+
Dependencies for IPython.kernel (parallel computing)
137+
====================================================
138+
139+
The IPython kernel provides a nice architecture for parallel computing. The main focus of this architecture is on interactive parallel computing. These features require a number of additional packages:
140+
141+
* zope.interface (yep, we use interfaces)
142+
* Twisted (asynchronous networking framework)
143+
* Foolscap (a nice, secure network protocol)
144+
* pyOpenSSL (security for network connections)
145+
146+
On a Unix style platform (including OS X), if you want to use :mod:`setuptools`, you can just do::
147+
148+
$ easy_install IPython[kernel] # the first three
149+
$ easy_install IPython[security] # pyOpenSSL
150+
151+
zope.interface and Twisted
152+
--------------------------
153+
154+
On Unix style platforms (including OS X), the simplest way of getting the these is to use :command:`easy_install`::
155+
156+
$ easy_install zope.interface
157+
$ easy_install Twisted
158+
159+
Of course, you can also download the source tarballs from the `Twisted website <twistedmatrix.org>`_ and the `zope.interface page at PyPI <http://pypi.python.org/pypi/zope.interface>`_ and do the usual ``python setup.py install`` if you prefer.
160+
161+
Windows is a bit different. For zope.interface and Twisted, simply get the latest binary ``.exe`` installer from the Twisted website. This installer includes both zope.interface and Twisted and should just work.
162+
163+
Foolscap
164+
--------
165+
166+
Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to implement our parallel computing features.
167+
168+
On all platforms a simple::
169+
170+
$ easy_install foolscap
171+
172+
should work. You can also download the source tarballs from the `Foolscap website <http://foolscap.lothar.com/trac>`_ and do ``python setup.py install`` if you prefer.
173+
174+
pyOpenSSL
175+
---------
176+
177+
IPython requires an older version of pyOpenSSL (0.6 rather than the current 0.7). There are a couple of options for getting this:
178+
179+
1. Most Linux distributions have packages for pyOpenSSL.
180+
2. The built-in Python 2.5 on OS X 10.5 already has it installed.
181+
3. There are source tarballs on the pyOpenSSL website. On Unix-like
182+
platforms, these can be built using ``python seutp.py install``.
183+
4. There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website <http://pyopenssl.sourceforge.net/>`_.
184+
185+
Dependencies for IPython.frontend (the IPython GUI)
186+
===================================================
187+
188+
wxPython
189+
--------
190+
191+
Starting with IPython 0.9, IPython has a new IPython.frontend package that has a nice wxPython based IPython GUI. As you would expect, this GUI requires wxPython. Most Linux distributions have wxPython packages available and the built-in Python on OS X comes with wxPython preinstalled. For Windows, a binary installer is available on the `wxPython website <http://www.wxpython.org/>`_.

0 commit comments

Comments
 (0)