##// END OF EJS Templates
upstream » ipython
RSS

Clone from https://github.com/ipython/ipython.git

Minor doc fixes for the 0.9 release....
Brian Granger -
Show More
Show file before | Show file after | Hide comments
@@ -1,191 +1,204 b''
1 Overview
1 Overview
2 ========
2 ========
3
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.
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
5
6
6
7 Please let us know if you have problems installing IPython or any of its
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
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.
9 IPython with the upcoming 2.6 or 3.0 versions.
10
10
11 .. warning::
11 .. warning::
12
12
13 IPython will not work with Python 2.3 or below.
13 IPython will not work with Python 2.3 or below.
14
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.
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
16
17 More general information about installing Python packages can be found in Python's documentation at http://www.python.org/doc/.
17 More general information about installing Python packages can be found in Python's documentation at http://www.python.org/doc/.
18
18
19 Quickstart
20 ==========
21
22 If you have :mod:`setuptools` installed and you are on OS X or Linux (not Windows), the following will download and install IPython *and* the main optional dependencies::
23
24 $ easy_install ipython[kernel,security,test]
25
26 This will get Twisted, zope.interface and Foolscap, which are needed for IPython's parallel computing features as well as the nose package, which will enable you to run IPython's test suite. To run IPython's test suite, use the :command:`iptest` command::
27
28 $ iptest
29
30 Read on for more specific details and instructions for Windows.
31
19 Installing IPython itself
32 Installing IPython itself
20 =========================
33 =========================
21
34
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`.
35 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
36
24 Installation using easy_install
37 Installation using easy_install
25 -------------------------------
38 -------------------------------
26
39
27 If you have :mod:`setuptools` installed, the easiest way of getting IPython is to simple use :command:`easy_install`::
40 If you have :mod:`setuptools` installed, the easiest way of getting IPython is to simple use :command:`easy_install`::
28
41
29 $ easy_install IPython
42 $ easy_install ipython
30
43
31 That's it.
44 That's it.
32
45
33 Installation from source
46 Installation from source
34 ------------------------
47 ------------------------
35
48
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::
49 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
50
38 $ tar -xzf ipython.tar.gz
51 $ tar -xzf ipython.tar.gz
39 $ cd ipython
52 $ cd ipython
40 $ python setup.py install
53 $ python setup.py install
41
54
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`.
55 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
56
44 Windows
57 Windows
45 -------
58 -------
46
59
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:
60 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
61
49 1. Install using :command:`easy_install`.
62 1. Install using :command:`easy_install`.
50
63
51 2. Install using our binary ``.exe`` Windows installer, which can be found at `here <http://ipython.scipy.org/dist/>`_
64 2. Install using our binary ``.exe`` Windows installer, which can be found at `here <http://ipython.scipy.org/dist/>`_
52
65
53 3. Install from source, but using :mod:`setuptools` (``python setupegg.py install``).
66 3. Install from source, but using :mod:`setuptools` (``python setupegg.py install``).
54
67
55 Installing the development version
68 Installing the development version
56 ----------------------------------
69 ----------------------------------
57
70
58 It is also possible to install the development version of IPython from our `Bazaar <http://bazaar-vcs.org/>`_ source code
71 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::
72 repository. To do this you will need to have Bazaar installed on your system. Then just do::
60
73
61 $ bzr branch lp:ipython
74 $ bzr branch lp:ipython
62 $ cd ipython
75 $ cd ipython
63 $ python setup.py install
76 $ python setup.py install
64
77
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.
78 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
79
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::
80 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
81
69 $ python setupegg.py develop
82 $ python setupegg.py develop
70
83
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::
84 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
85
73 $ bzr pull
86 $ bzr pull
74
87
75 Basic optional dependencies
88 Basic optional dependencies
76 ===========================
89 ===========================
77
90
78 There are a number of basic optional dependencies that most users will want to get. These are:
91 There are a number of basic optional dependencies that most users will want to get. These are:
79
92
80 * readline (for command line editing, tab completion, etc.)
93 * readline (for command line editing, tab completion, etc.)
81 * nose (to run the IPython test suite)
94 * nose (to run the IPython test suite)
82 * pexpect (to use things like irunner)
95 * pexpect (to use things like irunner)
83
96
84 If you are comfortable installing these things yourself, have at it, otherwise read on for more details.
97 If you are comfortable installing these things yourself, have at it, otherwise read on for more details.
85
98
86 readline
99 readline
87 --------
100 --------
88
101
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:
102 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
103
91 * If you are using the built-in Python on Mac OS X.
104 * If you are using the built-in Python on Mac OS X.
92
105
93 * If you are running Windows, which doesn't have a :mod:`readline` module.
106 * If you are running Windows, which doesn't have a :mod:`readline` module.
94
107
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.
108 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
109
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)::
110 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
111
99 $ easy_install readline
112 $ easy_install readline
100
113
101 .. note:
114 .. note:
102
115
103 Other Python distributions on OS X (such as fink, MacPorts and the
116 Other Python distributions on OS X (such as fink, MacPorts and the
104 official python.org binaries) already have readline installed so
117 official python.org binaries) already have readline installed so
105 you don't have to do this step.
118 you don't have to do this step.
106
119
107 If needed, the readline egg can be build and installed from source (see the wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
120 If needed, the readline egg can be build and installed from source (see the wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
108
121
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.
122 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
123
111 nose
124 nose
112 ----
125 ----
113
126
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`::
127 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
128
116 $ easy_install nose
129 $ easy_install nose
117
130
118 Another way of getting this is to do::
131 Another way of getting this is to do::
119
132
120 $ easy_install IPython[test]
133 $ easy_install ipython[test]
121
134
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::
135 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
136
124 $ iptest
137 $ iptest
125
138
126
139
127 pexpect
140 pexpect
128 -------
141 -------
129
142
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::
143 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
144
132 $ easy_install pexpect
145 $ easy_install pexpect
133
146
134 Windows users are out of luck as pexpect does not run there.
147 Windows users are out of luck as pexpect does not run there.
135
148
136 Dependencies for IPython.kernel (parallel computing)
149 Dependencies for IPython.kernel (parallel computing)
137 ====================================================
150 ====================================================
138
151
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:
152 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
153
141 * zope.interface (yep, we use interfaces)
154 * zope.interface (yep, we use interfaces)
142 * Twisted (asynchronous networking framework)
155 * Twisted (asynchronous networking framework)
143 * Foolscap (a nice, secure network protocol)
156 * Foolscap (a nice, secure network protocol)
144 * pyOpenSSL (security for network connections)
157 * pyOpenSSL (security for network connections)
145
158
146 On a Unix style platform (including OS X), if you want to use :mod:`setuptools`, you can just do::
159 On a Unix style platform (including OS X), if you want to use :mod:`setuptools`, you can just do::
147
160
148 $ easy_install IPython[kernel] # the first three
161 $ easy_install ipython[kernel] # the first three
149 $ easy_install IPython[security] # pyOpenSSL
162 $ easy_install ipython[security] # pyOpenSSL
150
163
151 zope.interface and Twisted
164 zope.interface and Twisted
152 --------------------------
165 --------------------------
153
166
154 On Unix style platforms (including OS X), the simplest way of getting the these is to use :command:`easy_install`::
167 On Unix style platforms (including OS X), the simplest way of getting the these is to use :command:`easy_install`::
155
168
156 $ easy_install zope.interface
169 $ easy_install zope.interface
157 $ easy_install Twisted
170 $ easy_install Twisted
158
171
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.
172 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
173
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.
174 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
175
163 Foolscap
176 Foolscap
164 --------
177 --------
165
178
166 Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to implement our parallel computing features.
179 Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to implement our parallel computing features.
167
180
168 On all platforms a simple::
181 On all platforms a simple::
169
182
170 $ easy_install foolscap
183 $ easy_install foolscap
171
184
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.
185 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
186
174 pyOpenSSL
187 pyOpenSSL
175 ---------
188 ---------
176
189
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:
190 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
191
179 1. Most Linux distributions have packages for pyOpenSSL.
192 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.
193 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
194 3. There are source tarballs on the pyOpenSSL website. On Unix-like
182 platforms, these can be built using ``python seutp.py install``.
195 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/>`_.
196 4. There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website <http://pyopenssl.sourceforge.net/>`_.
184
197
185 Dependencies for IPython.frontend (the IPython GUI)
198 Dependencies for IPython.frontend (the IPython GUI)
186 ===================================================
199 ===================================================
187
200
188 wxPython
201 wxPython
189 --------
202 --------
190
203
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/>`_. No newline at end of file
204 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/>`_.
General Comments 0
You need to be logged in to leave comments. Login now