##// END OF EJS Templates
Add documentation note about windows 64-bit installation procedure....
Fernando Perez -
Show More
@@ -1,341 +1,349 b''
1 Overview
1 Overview
2 ========
2 ========
3
3
4 This document describes the steps required to install IPython. IPython is
4 This document describes the steps required to install IPython. IPython is
5 organized into a number of subpackages, each of which has its own dependencies.
5 organized into a number of subpackages, each of which has its own dependencies.
6 All of the subpackages come with IPython, so you don't need to download and
6 All of the subpackages come with IPython, so you don't need to download and
7 install them separately. However, to use a given subpackage, you will need to
7 install them separately. However, to use a given subpackage, you will need to
8 install all of its dependencies.
8 install all of its dependencies.
9
9
10
10
11 Please let us know if you have problems installing IPython or any of its
11 Please let us know if you have problems installing IPython or any of its
12 dependencies. Officially, IPython requires Python version 2.5 or 2.6. We
12 dependencies. Officially, IPython requires Python version 2.5 or 2.6. We
13 have *not* yet started to port IPython to Python 3.0.
13 have *not* yet started to port IPython to Python 3.0.
14
14
15 .. warning::
15 .. warning::
16
16
17 Officially, IPython supports Python versions 2.5 and 2.6.
17 Officially, IPython supports Python versions 2.5 and 2.6.
18
18
19 IPython 0.10 has only been well tested with Python 2.5 and 2.6. Parts of
19 IPython 0.10 has only been well tested with Python 2.5 and 2.6. Parts of
20 it may work with Python 2.4, but we do not officially support Python 2.4
20 it may work with Python 2.4, but we do not officially support Python 2.4
21 anymore. If you need to use 2.4, you can still run IPython 0.9.
21 anymore. If you need to use 2.4, you can still run IPython 0.9.
22
22
23 Some of the installation approaches use the :mod:`setuptools` package and its
23 Some of the installation approaches use the :mod:`setuptools` package and its
24 :command:`easy_install` command line program. In many scenarios, this provides
24 :command:`easy_install` command line program. In many scenarios, this provides
25 the most simple method of installing IPython and its dependencies. It is not
25 the most simple method of installing IPython and its dependencies. It is not
26 required though. More information about :mod:`setuptools` can be found on its
26 required though. More information about :mod:`setuptools` can be found on its
27 website.
27 website.
28
28
29 More general information about installing Python packages can be found in
29 More general information about installing Python packages can be found in
30 Python's documentation at http://www.python.org/doc/.
30 Python's documentation at http://www.python.org/doc/.
31
31
32 Quickstart
32 Quickstart
33 ==========
33 ==========
34
34
35 If you have :mod:`setuptools` installed and you are on OS X or Linux (not
35 If you have :mod:`setuptools` installed and you are on OS X or Linux (not
36 Windows), the following will download and install IPython *and* the main
36 Windows), the following will download and install IPython *and* the main
37 optional dependencies:
37 optional dependencies:
38
38
39 .. code-block:: bash
39 .. code-block:: bash
40
40
41 $ easy_install ipython[kernel,security,test]
41 $ easy_install ipython[kernel,security,test]
42
42
43 This will get Twisted, zope.interface and Foolscap, which are needed for
43 This will get Twisted, zope.interface and Foolscap, which are needed for
44 IPython's parallel computing features as well as the nose package, which will
44 IPython's parallel computing features as well as the nose package, which will
45 enable you to run IPython's test suite.
45 enable you to run IPython's test suite.
46
46
47 .. warning::
47 .. warning::
48
48
49 IPython's test system is being refactored and currently the
49 IPython's test system is being refactored and currently the
50 :command:`iptest` shown below does not work. More details about the
50 :command:`iptest` shown below does not work. More details about the
51 testing situation can be found :ref:`here <testing>`
51 testing situation can be found :ref:`here <testing>`
52
52
53 To run IPython's test suite, use the :command:`iptest` command:
53 To run IPython's test suite, use the :command:`iptest` command:
54
54
55 .. code-block:: bash
55 .. code-block:: bash
56
56
57 $ iptest
57 $ iptest
58
58
59 Read on for more specific details and instructions for Windows.
59 Read on for more specific details and instructions for Windows.
60
60
61 Installing IPython itself
61 Installing IPython itself
62 =========================
62 =========================
63
63
64 Given a properly built Python, the basic interactive IPython shell will work
64 Given a properly built Python, the basic interactive IPython shell will work
65 with no external dependencies. However, some Python distributions
65 with no external dependencies. However, some Python distributions
66 (particularly on Windows and OS X), don't come with a working :mod:`readline`
66 (particularly on Windows and OS X), don't come with a working :mod:`readline`
67 module. The IPython shell will work without :mod:`readline`, but will lack
67 module. The IPython shell will work without :mod:`readline`, but will lack
68 many features that users depend on, such as tab completion and command line
68 many features that users depend on, such as tab completion and command line
69 editing. See below for details of how to make sure you have a working
69 editing. See below for details of how to make sure you have a working
70 :mod:`readline`.
70 :mod:`readline`.
71
71
72 Installation using easy_install
72 Installation using easy_install
73 -------------------------------
73 -------------------------------
74
74
75 If you have :mod:`setuptools` installed, the easiest way of getting IPython is
75 If you have :mod:`setuptools` installed, the easiest way of getting IPython is
76 to simple use :command:`easy_install`:
76 to simple use :command:`easy_install`:
77
77
78 .. code-block:: bash
78 .. code-block:: bash
79
79
80 $ easy_install ipython
80 $ easy_install ipython
81
81
82 That's it.
82 That's it.
83
83
84 Installation from source
84 Installation from source
85 ------------------------
85 ------------------------
86
86
87 If you don't want to use :command:`easy_install`, or don't have it installed,
87 If you don't want to use :command:`easy_install`, or don't have it installed,
88 just grab the latest stable build of IPython from `here
88 just grab the latest stable build of IPython from `here
89 <http://ipython.scipy.org/dist/>`_. Then do the following:
89 <http://ipython.scipy.org/dist/>`_. Then do the following:
90
90
91 .. code-block:: bash
91 .. code-block:: bash
92
92
93 $ tar -xzf ipython.tar.gz
93 $ tar -xzf ipython.tar.gz
94 $ cd ipython
94 $ cd ipython
95 $ python setup.py install
95 $ python setup.py install
96
96
97 If you are installing to a location (like ``/usr/local``) that requires higher
97 If you are installing to a location (like ``/usr/local``) that requires higher
98 permissions, you may need to run the last command with :command:`sudo`.
98 permissions, you may need to run the last command with :command:`sudo`.
99
99
100 Windows
100 Windows
101 -------
101 -------
102
102
103 There are a few caveats for Windows users. The main issue is that a basic
103 There are a few caveats for Windows users. The main issue is that a basic
104 ``python setup.py install`` approach won't create ``.bat`` file or Start Menu
104 ``python setup.py install`` approach won't create ``.bat`` file or Start Menu
105 shortcuts, which most users want. To get an installation with these, you can
105 shortcuts, which most users want. To get an installation with these, you can
106 use any of the following alternatives:
106 use any of the following alternatives:
107
107
108 1. Install using :command:`easy_install`.
108 1. Install using :command:`easy_install`.
109
109
110 2. Install using our binary ``.exe`` Windows installer, which can be found at
110 2. Install using our binary ``.exe`` Windows installer, which can be found at
111 `here <http://ipython.scipy.org/dist/>`_
111 `here <http://ipython.scipy.org/dist/>`_
112
112
113 3. Install from source, but using :mod:`setuptools` (``python setupegg.py
113 3. Install from source, but using :mod:`setuptools` (``python setupegg.py
114 install``).
114 install``).
115
115
116 IPython by default runs in a terminal window, but the normal terminal
116 IPython by default runs in a terminal window, but the normal terminal
117 application supplied by Microsoft Windows is very primitive. You may want to
117 application supplied by Microsoft Windows is very primitive. You may want to
118 download the excellent and free Console_ application instead, which is a far
118 download the excellent and free Console_ application instead, which is a far
119 superior tool. You can even configure Console to give you by default an
119 superior tool. You can even configure Console to give you by default an
120 IPython tab, which is very convenient to create new IPython sessions directly
120 IPython tab, which is very convenient to create new IPython sessions directly
121 from the working terminal.
121 from the working terminal.
122
122
123 .. _Console: http://sourceforge.net/projects/console
123 .. _Console: http://sourceforge.net/projects/console
124
124
125 Note for Windows 64 bit users: you may have difficulties with the stock
126 installer on 64 bit systems; in this case (since we currently do not have 64
127 bit builds of the Windows installer) your best bet is to install from source
128 with the setuptools method indicated in #3 above. See `this bug report`_ for
129 further details.
130
131 .. _this bug report: https://bugs.launchpad.net/ipython/+bug/382214
132
125
133
126 Installing the development version
134 Installing the development version
127 ----------------------------------
135 ----------------------------------
128
136
129 It is also possible to install the development version of IPython from our
137 It is also possible to install the development version of IPython from our
130 `Bazaar <http://bazaar-vcs.org/>`_ source code repository. To do this you will
138 `Bazaar <http://bazaar-vcs.org/>`_ source code repository. To do this you will
131 need to have Bazaar installed on your system. Then just do:
139 need to have Bazaar installed on your system. Then just do:
132
140
133 .. code-block:: bash
141 .. code-block:: bash
134
142
135 $ bzr branch lp:ipython
143 $ bzr branch lp:ipython
136 $ cd ipython
144 $ cd ipython
137 $ python setup.py install
145 $ python setup.py install
138
146
139 Again, this last step on Windows won't create ``.bat`` files or Start Menu
147 Again, this last step on Windows won't create ``.bat`` files or Start Menu
140 shortcuts, so you will have to use one of the other approaches listed above.
148 shortcuts, so you will have to use one of the other approaches listed above.
141
149
142 Some users want to be able to follow the development branch as it changes. If
150 Some users want to be able to follow the development branch as it changes. If
143 you have :mod:`setuptools` installed, this is easy. Simply replace the last
151 you have :mod:`setuptools` installed, this is easy. Simply replace the last
144 step by:
152 step by:
145
153
146 .. code-block:: bash
154 .. code-block:: bash
147
155
148 $ python setupegg.py develop
156 $ python setupegg.py develop
149
157
150 This creates links in the right places and installs the command line script to
158 This creates links in the right places and installs the command line script to
151 the appropriate places. Then, if you want to update your IPython at any time,
159 the appropriate places. Then, if you want to update your IPython at any time,
152 just do:
160 just do:
153
161
154 .. code-block:: bash
162 .. code-block:: bash
155
163
156 $ bzr pull
164 $ bzr pull
157
165
158 Basic optional dependencies
166 Basic optional dependencies
159 ===========================
167 ===========================
160
168
161 There are a number of basic optional dependencies that most users will want to
169 There are a number of basic optional dependencies that most users will want to
162 get. These are:
170 get. These are:
163
171
164 * readline (for command line editing, tab completion, etc.)
172 * readline (for command line editing, tab completion, etc.)
165 * nose (to run the IPython test suite)
173 * nose (to run the IPython test suite)
166 * pexpect (to use things like irunner)
174 * pexpect (to use things like irunner)
167
175
168 If you are comfortable installing these things yourself, have at it, otherwise
176 If you are comfortable installing these things yourself, have at it, otherwise
169 read on for more details.
177 read on for more details.
170
178
171 readline
179 readline
172 --------
180 --------
173
181
174 In principle, all Python distributions should come with a working
182 In principle, all Python distributions should come with a working
175 :mod:`readline` module. But, reality is not quite that simple. There are two
183 :mod:`readline` module. But, reality is not quite that simple. There are two
176 common situations where you won't have a working :mod:`readline` module:
184 common situations where you won't have a working :mod:`readline` module:
177
185
178 * If you are using the built-in Python on Mac OS X.
186 * If you are using the built-in Python on Mac OS X.
179
187
180 * If you are running Windows, which doesn't have a :mod:`readline` module.
188 * If you are running Windows, which doesn't have a :mod:`readline` module.
181
189
182 On OS X, the built-in Python doesn't not have :mod:`readline` because of
190 On OS X, the built-in Python doesn't not have :mod:`readline` because of
183 license issues. Starting with OS X 10.5 (Leopard), Apple's built-in Python has
191 license issues. Starting with OS X 10.5 (Leopard), Apple's built-in Python has
184 a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9,
192 a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9,
185 many of the issues related to the differences between readline and libedit have
193 many of the issues related to the differences between readline and libedit have
186 been resolved. For many users, libedit may be sufficient.
194 been resolved. For many users, libedit may be sufficient.
187
195
188 Most users on OS X will want to get the full :mod:`readline` module. To get a
196 Most users on OS X will want to get the full :mod:`readline` module. To get a
189 working :mod:`readline` module, just do (with :mod:`setuptools` installed):
197 working :mod:`readline` module, just do (with :mod:`setuptools` installed):
190
198
191 .. code-block:: bash
199 .. code-block:: bash
192
200
193 $ easy_install readline
201 $ easy_install readline
194
202
195 .. note::
203 .. note::
196
204
197 Other Python distributions on OS X (such as fink, MacPorts and the
205 Other Python distributions on OS X (such as fink, MacPorts and the
198 official python.org binaries) already have readline installed so
206 official python.org binaries) already have readline installed so
199 you don't have to do this step.
207 you don't have to do this step.
200
208
201 If needed, the readline egg can be build and installed from source (see the
209 If needed, the readline egg can be build and installed from source (see the
202 wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
210 wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
203
211
204 On Windows, you will need the PyReadline module. PyReadline is a separate,
212 On Windows, you will need the PyReadline module. PyReadline is a separate,
205 Windows only implementation of readline that uses native Windows calls through
213 Windows only implementation of readline that uses native Windows calls through
206 :mod:`ctypes`. The easiest way of installing PyReadline is you use the binary
214 :mod:`ctypes`. The easiest way of installing PyReadline is you use the binary
207 installer available `here <http://ipython.scipy.org/dist/>`_. The :mod:`ctypes`
215 installer available `here <http://ipython.scipy.org/dist/>`_. The :mod:`ctypes`
208 module, which comes with Python 2.5 and greater, is required by PyReadline. It
216 module, which comes with Python 2.5 and greater, is required by PyReadline. It
209 is available for Python 2.4 at http://python.net/crew/theller/ctypes.
217 is available for Python 2.4 at http://python.net/crew/theller/ctypes.
210
218
211 nose
219 nose
212 ----
220 ----
213
221
214 To run the IPython test suite you will need the :mod:`nose` package. Nose
222 To run the IPython test suite you will need the :mod:`nose` package. Nose
215 provides a great way of sniffing out and running all of the IPython tests. The
223 provides a great way of sniffing out and running all of the IPython tests. The
216 simplest way of getting nose, is to use :command:`easy_install`:
224 simplest way of getting nose, is to use :command:`easy_install`:
217
225
218 .. code-block:: bash
226 .. code-block:: bash
219
227
220 $ easy_install nose
228 $ easy_install nose
221
229
222 Another way of getting this is to do:
230 Another way of getting this is to do:
223
231
224 .. code-block:: bash
232 .. code-block:: bash
225
233
226 $ easy_install ipython[test]
234 $ easy_install ipython[test]
227
235
228 For more installation options, see the `nose website
236 For more installation options, see the `nose website
229 <http://somethingaboutorange.com/mrl/projects/nose/>`_.
237 <http://somethingaboutorange.com/mrl/projects/nose/>`_.
230
238
231 .. warning::
239 .. warning::
232
240
233 As described above, the :command:`iptest` command currently doesn't work.
241 As described above, the :command:`iptest` command currently doesn't work.
234
242
235 Once you have nose installed, you can run IPython's test suite using the
243 Once you have nose installed, you can run IPython's test suite using the
236 iptest command:
244 iptest command:
237
245
238 .. code-block:: bash
246 .. code-block:: bash
239
247
240 $ iptest
248 $ iptest
241
249
242 pexpect
250 pexpect
243 -------
251 -------
244
252
245 The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's
253 The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's
246 :command:`irunner` script. On Unix platforms (including OS X), just do:
254 :command:`irunner` script. On Unix platforms (including OS X), just do:
247
255
248 .. code-block:: bash
256 .. code-block:: bash
249
257
250 $ easy_install pexpect
258 $ easy_install pexpect
251
259
252 Windows users are out of luck as pexpect does not run there.
260 Windows users are out of luck as pexpect does not run there.
253
261
254 Dependencies for IPython.kernel (parallel computing)
262 Dependencies for IPython.kernel (parallel computing)
255 ====================================================
263 ====================================================
256
264
257 The IPython kernel provides a nice architecture for parallel computing. The
265 The IPython kernel provides a nice architecture for parallel computing. The
258 main focus of this architecture is on interactive parallel computing. These
266 main focus of this architecture is on interactive parallel computing. These
259 features require a number of additional packages:
267 features require a number of additional packages:
260
268
261 * zope.interface (yep, we use interfaces)
269 * zope.interface (yep, we use interfaces)
262 * Twisted (asynchronous networking framework)
270 * Twisted (asynchronous networking framework)
263 * Foolscap (a nice, secure network protocol)
271 * Foolscap (a nice, secure network protocol)
264 * pyOpenSSL (security for network connections)
272 * pyOpenSSL (security for network connections)
265
273
266 On a Unix style platform (including OS X), if you want to use
274 On a Unix style platform (including OS X), if you want to use
267 :mod:`setuptools`, you can just do:
275 :mod:`setuptools`, you can just do:
268
276
269 .. code-block:: bash
277 .. code-block:: bash
270
278
271 $ easy_install ipython[kernel] # the first three
279 $ easy_install ipython[kernel] # the first three
272 $ easy_install ipython[security] # pyOpenSSL
280 $ easy_install ipython[security] # pyOpenSSL
273
281
274 zope.interface and Twisted
282 zope.interface and Twisted
275 --------------------------
283 --------------------------
276
284
277 Twisted [Twisted]_ and zope.interface [ZopeInterface]_ are used for networking
285 Twisted [Twisted]_ and zope.interface [ZopeInterface]_ are used for networking
278 related things. On Unix style platforms (including OS X), the simplest way of
286 related things. On Unix style platforms (including OS X), the simplest way of
279 getting the these is to use :command:`easy_install`:
287 getting the these is to use :command:`easy_install`:
280
288
281 .. code-block:: bash
289 .. code-block:: bash
282
290
283 $ easy_install zope.interface
291 $ easy_install zope.interface
284 $ easy_install Twisted
292 $ easy_install Twisted
285
293
286 Of course, you can also download the source tarballs from the Twisted website
294 Of course, you can also download the source tarballs from the Twisted website
287 [Twisted]_ and the
295 [Twisted]_ and the
288 `zope.interface page at PyPI <http://pypi.python.org/pypi/zope.interface>`_
296 `zope.interface page at PyPI <http://pypi.python.org/pypi/zope.interface>`_
289 and do the usual ``python setup.py install`` if you prefer.
297 and do the usual ``python setup.py install`` if you prefer.
290
298
291 Windows is a bit different. For zope.interface and Twisted, simply get the
299 Windows is a bit different. For zope.interface and Twisted, simply get the
292 latest binary ``.exe`` installer from the Twisted website. This installer
300 latest binary ``.exe`` installer from the Twisted website. This installer
293 includes both zope.interface and Twisted and should just work.
301 includes both zope.interface and Twisted and should just work.
294
302
295 Foolscap
303 Foolscap
296 --------
304 --------
297
305
298 Foolscap [Foolscap]_ uses Twisted to provide a very nice secure RPC protocol that we use to implement our parallel computing features.
306 Foolscap [Foolscap]_ uses Twisted to provide a very nice secure RPC protocol that we use to implement our parallel computing features.
299
307
300 On all platforms a simple:
308 On all platforms a simple:
301
309
302 .. code-block:: bash
310 .. code-block:: bash
303
311
304 $ easy_install foolscap
312 $ easy_install foolscap
305
313
306 should work. You can also download the source tarballs from the `Foolscap
314 should work. You can also download the source tarballs from the `Foolscap
307 website <http://foolscap.lothar.com/trac>`_ and do ``python setup.py install``
315 website <http://foolscap.lothar.com/trac>`_ and do ``python setup.py install``
308 if you prefer.
316 if you prefer.
309
317
310 pyOpenSSL
318 pyOpenSSL
311 ---------
319 ---------
312
320
313 IPython does not work with version 0.7 of pyOpenSSL [pyOpenSSL]_. It is known
321 IPython does not work with version 0.7 of pyOpenSSL [pyOpenSSL]_. It is known
314 to work with version 0.6 and will likely work with the more recent 0.8 and 0.9
322 to work with version 0.6 and will likely work with the more recent 0.8 and 0.9
315 versions. There are a couple of options for getting this:
323 versions. There are a couple of options for getting this:
316
324
317 1. Most Linux distributions have packages for pyOpenSSL.
325 1. Most Linux distributions have packages for pyOpenSSL.
318 2. The built-in Python 2.5 on OS X 10.5 already has it installed.
326 2. The built-in Python 2.5 on OS X 10.5 already has it installed.
319 3. There are source tarballs on the pyOpenSSL website. On Unix-like
327 3. There are source tarballs on the pyOpenSSL website. On Unix-like
320 platforms, these can be built using ``python seutp.py install``.
328 platforms, these can be built using ``python seutp.py install``.
321 4. There is also a binary ``.exe`` Windows installer on the
329 4. There is also a binary ``.exe`` Windows installer on the
322 `pyOpenSSL website <http://pyopenssl.sourceforge.net/>`_.
330 `pyOpenSSL website <http://pyopenssl.sourceforge.net/>`_.
323
331
324 Dependencies for IPython.frontend (the IPython GUI)
332 Dependencies for IPython.frontend (the IPython GUI)
325 ===================================================
333 ===================================================
326
334
327 wxPython
335 wxPython
328 --------
336 --------
329
337
330 Starting with IPython 0.9, IPython has a new :mod:`IPython.frontend` package
338 Starting with IPython 0.9, IPython has a new :mod:`IPython.frontend` package
331 that has a nice wxPython based IPython GUI. As you would expect, this GUI
339 that has a nice wxPython based IPython GUI. As you would expect, this GUI
332 requires wxPython. Most Linux distributions have wxPython packages available
340 requires wxPython. Most Linux distributions have wxPython packages available
333 and the built-in Python on OS X comes with wxPython preinstalled. For Windows,
341 and the built-in Python on OS X comes with wxPython preinstalled. For Windows,
334 a binary installer is available on the `wxPython website
342 a binary installer is available on the `wxPython website
335 <http://www.wxpython.org/>`_.
343 <http://www.wxpython.org/>`_.
336
344
337 .. [Twisted] Twisted matrix. http://twistedmatrix.org
345 .. [Twisted] Twisted matrix. http://twistedmatrix.org
338 .. [ZopeInterface] http://pypi.python.org/pypi/zope.interface
346 .. [ZopeInterface] http://pypi.python.org/pypi/zope.interface
339 .. [Foolscap] Foolscap network protocol. http://foolscap.lothar.com/trac
347 .. [Foolscap] Foolscap network protocol. http://foolscap.lothar.com/trac
340 .. [pyOpenSSL] pyOpenSSL. http://pyopenssl.sourceforge.net
348 .. [pyOpenSSL] pyOpenSSL. http://pyopenssl.sourceforge.net
341
349
General Comments 0
You need to be logged in to leave comments. Login now