##// END OF EJS Templates
add note about Windows setuptools dependency to install doc
MinRK -
Show More
@@ -1,331 +1,345 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.6 or 2.7. There
12 dependencies. Officially, IPython requires Python version 2.6 or 2.7. There
13 is an experimental port of IPython for Python3 `on GitHub
13 is an experimental port of IPython for Python3 `on GitHub
14 <https://github.com/ipython/ipython-py3k>`_
14 <https://github.com/ipython/ipython-py3k>`_
15
15
16 .. warning::
16 .. warning::
17
17
18 Officially, IPython supports Python versions 2.6 and 2.7.
18 Officially, IPython supports Python versions 2.6 and 2.7.
19
19
20 IPython 0.11 has a hard syntax dependency on 2.6, and will no longer work
20 IPython 0.11 has a hard syntax dependency on 2.6, and will no longer work
21 on Python <= 2.5.
21 on Python <= 2.5.
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 .. note::
30
31 On Windows, IPython *does* depend on :mod:`setuptools`, and it is recommended
32 that you install the :mod:`distribute` package, which improves
33 :mod:`setuptools` and fixes various bugs.
34
35 We hope to remove this dependency in 0.12.
36
29 More general information about installing Python packages can be found in
37 More general information about installing Python packages can be found in
30 Python's documentation at http://www.python.org/doc/.
38 Python's documentation at http://www.python.org/doc/.
31
39
32 Quickstart
40 Quickstart
33 ==========
41 ==========
34
42
35 If you have :mod:`setuptools` installed and you are on OS X or Linux (not
43 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
44 Windows), the following will download and install IPython *and* the main
37 optional dependencies:
45 optional dependencies:
38
46
39 .. code-block:: bash
47 .. code-block:: bash
40
48
41 $ easy_install ipython[zmq,test]
49 $ easy_install ipython[zmq,test]
42
50
43 This will get pyzmq, which is needed for
51 This will get pyzmq, which is needed for
44 IPython's parallel computing features as well as the nose package, which will
52 IPython's parallel computing features as well as the nose package, which will
45 enable you to run IPython's test suite.
53 enable you to run IPython's test suite.
46
54
47 .. warning::
55 .. warning::
48
56
49 IPython's test system is being refactored and currently the
57 IPython's test system is being refactored and currently the
50 :command:`iptest` shown below does not work. More details about the
58 :command:`iptest` shown below does not work. More details about the
51 testing situation can be found :ref:`here <testing>`
59 testing situation can be found :ref:`here <testing>`
52
60
53 To run IPython's test suite, use the :command:`iptest` command:
61 To run IPython's test suite, use the :command:`iptest` command:
54
62
55 .. code-block:: bash
63 .. code-block:: bash
56
64
57 $ iptest
65 $ iptest
58
66
59 Read on for more specific details and instructions for Windows.
67 Read on for more specific details and instructions for Windows.
60
68
61 Installing IPython itself
69 Installing IPython itself
62 =========================
70 =========================
63
71
64 Given a properly built Python, the basic interactive IPython shell will work
72 Given a properly built Python, the basic interactive IPython shell will work
65 with no external dependencies. However, some Python distributions
73 with no external dependencies. However, some Python distributions
66 (particularly on Windows and OS X), don't come with a working :mod:`readline`
74 (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
75 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
76 many features that users depend on, such as tab completion and command line
69 editing. If you install IPython with :mod:`setuptools`, (e.g. with `easy_install`),
77 editing. If you install IPython with :mod:`setuptools`, (e.g. with `easy_install`),
70 then the appropriate :mod:`readline` for your platform will be installed.
78 then the appropriate :mod:`readline` for your platform will be installed.
71 See below for details of how to make sure you have a working :mod:`readline`.
79 See below for details of how to make sure you have a working :mod:`readline`.
72
80
73 Installation using easy_install
81 Installation using easy_install
74 -------------------------------
82 -------------------------------
75
83
76 If you have :mod:`setuptools` installed, the easiest way of getting IPython is
84 If you have :mod:`setuptools` installed, the easiest way of getting IPython is
77 to simple use :command:`easy_install`:
85 to simple use :command:`easy_install`:
78
86
79 .. code-block:: bash
87 .. code-block:: bash
80
88
81 $ easy_install ipython
89 $ easy_install ipython
82
90
83 That's it.
91 That's it.
84
92
85 Installation from source
93 Installation from source
86 ------------------------
94 ------------------------
87
95
88 If you don't want to use :command:`easy_install`, or don't have it installed,
96 If you don't want to use :command:`easy_install`, or don't have it installed,
89 just grab the latest stable build of IPython from `here
97 just grab the latest stable build of IPython from `here
90 <https://github.com/ipython/ipython/downloads>`_. Then do the following:
98 <https://github.com/ipython/ipython/downloads>`_. Then do the following:
91
99
92 .. code-block:: bash
100 .. code-block:: bash
93
101
94 $ tar -xzf ipython.tar.gz
102 $ tar -xzf ipython.tar.gz
95 $ cd ipython
103 $ cd ipython
96 $ python setup.py install
104 $ python setup.py install
97
105
98 If you are installing to a location (like ``/usr/local``) that requires higher
106 If you are installing to a location (like ``/usr/local``) that requires higher
99 permissions, you may need to run the last command with :command:`sudo`.
107 permissions, you may need to run the last command with :command:`sudo`.
100
108
101 Windows
109 Windows
102 -------
110 -------
103
111
112 .. note::
113
114 On Windows, IPython requires :mod:`setuptools` or :mod:`distribute`.
115
116 We hope to remove this dependency in 0.12.
117
104 There are a few caveats for Windows users. The main issue is that a basic
118 There are a few caveats for Windows users. The main issue is that a basic
105 ``python setup.py install`` approach won't create ``.bat`` file or Start Menu
119 ``python setup.py install`` approach won't create ``.bat`` file or Start Menu
106 shortcuts, which most users want. To get an installation with these, you can
120 shortcuts, which most users want. To get an installation with these, you can
107 use any of the following alternatives:
121 use any of the following alternatives:
108
122
109 1. Install using :command:`easy_install`.
123 1. Install using :command:`easy_install`.
110
124
111 2. Install using our binary ``.exe`` Windows installer, which can be found
125 2. Install using our binary ``.exe`` Windows installer, which can be found
112 `here <http://ipython.scipy.org/dist/>`_
126 `here <http://ipython.scipy.org/dist/>`_
113
127
114 3. Install from source, but using :mod:`setuptools` (``python setupegg.py
128 3. Install from source, but using :mod:`setuptools` (``python setupegg.py
115 install``).
129 install``).
116
130
117 IPython by default runs in a terminal window, but the normal terminal
131 IPython by default runs in a terminal window, but the normal terminal
118 application supplied by Microsoft Windows is very primitive. You may want to
132 application supplied by Microsoft Windows is very primitive. You may want to
119 download the excellent and free Console_ application instead, which is a far
133 download the excellent and free Console_ application instead, which is a far
120 superior tool. You can even configure Console to give you by default an
134 superior tool. You can even configure Console to give you by default an
121 IPython tab, which is very convenient to create new IPython sessions directly
135 IPython tab, which is very convenient to create new IPython sessions directly
122 from the working terminal.
136 from the working terminal.
123
137
124 .. _Console: http://sourceforge.net/projects/console
138 .. _Console: http://sourceforge.net/projects/console
125
139
126 Note for Windows 64 bit users: you may have difficulties with the stock
140 Note for Windows 64 bit users: you may have difficulties with the stock
127 installer on 64 bit systems; in this case (since we currently do not have 64
141 installer on 64 bit systems; in this case (since we currently do not have 64
128 bit builds of the Windows installer) your best bet is to install from source
142 bit builds of the Windows installer) your best bet is to install from source
129 with the setuptools method indicated in #3 above. See `this bug report`_ for
143 with the setuptools method indicated in #3 above. See `this bug report`_ for
130 further details.
144 further details.
131
145
132 .. _this bug report: https://bugs.launchpad.net/ipython/+bug/382214
146 .. _this bug report: https://bugs.launchpad.net/ipython/+bug/382214
133
147
134
148
135 Installing the development version
149 Installing the development version
136 ----------------------------------
150 ----------------------------------
137
151
138 It is also possible to install the development version of IPython from our
152 It is also possible to install the development version of IPython from our
139 `Git <http://git-scm.com/>`_ source code repository. To do this you will
153 `Git <http://git-scm.com/>`_ source code repository. To do this you will
140 need to have Git installed on your system. Then just do:
154 need to have Git installed on your system. Then just do:
141
155
142 .. code-block:: bash
156 .. code-block:: bash
143
157
144 $ git clone https://github.com/ipython/ipython.git
158 $ git clone https://github.com/ipython/ipython.git
145 $ cd ipython
159 $ cd ipython
146 $ python setup.py install
160 $ python setup.py install
147
161
148 Again, this last step on Windows won't create ``.bat`` files or Start Menu
162 Again, this last step on Windows won't create ``.bat`` files or Start Menu
149 shortcuts, so you will have to use one of the other approaches listed above.
163 shortcuts, so you will have to use one of the other approaches listed above.
150
164
151 Some users want to be able to follow the development branch as it changes. If
165 Some users want to be able to follow the development branch as it changes. If
152 you have :mod:`setuptools` installed, this is easy. Simply replace the last
166 you have :mod:`setuptools` installed, this is easy. Simply replace the last
153 step by:
167 step by:
154
168
155 .. code-block:: bash
169 .. code-block:: bash
156
170
157 $ python setupegg.py develop
171 $ python setupegg.py develop
158
172
159 This creates links in the right places and installs the command line script to
173 This creates links in the right places and installs the command line script to
160 the appropriate places. Then, if you want to update your IPython at any time,
174 the appropriate places. Then, if you want to update your IPython at any time,
161 just do:
175 just do:
162
176
163 .. code-block:: bash
177 .. code-block:: bash
164
178
165 $ git pull
179 $ git pull
166
180
167 Basic optional dependencies
181 Basic optional dependencies
168 ===========================
182 ===========================
169
183
170 There are a number of basic optional dependencies that most users will want to
184 There are a number of basic optional dependencies that most users will want to
171 get. These are:
185 get. These are:
172
186
173 * readline (for command line editing, tab completion, etc.)
187 * readline (for command line editing, tab completion, etc.)
174 * nose (to run the IPython test suite)
188 * nose (to run the IPython test suite)
175 * pexpect (to use things like irunner)
189 * pexpect (to use things like irunner)
176
190
177 If you are comfortable installing these things yourself, have at it, otherwise
191 If you are comfortable installing these things yourself, have at it, otherwise
178 read on for more details.
192 read on for more details.
179
193
180 readline
194 readline
181 --------
195 --------
182
196
183 In principle, all Python distributions should come with a working
197 In principle, all Python distributions should come with a working
184 :mod:`readline` module. But, reality is not quite that simple. There are two
198 :mod:`readline` module. But, reality is not quite that simple. There are two
185 common situations where you won't have a working :mod:`readline` module:
199 common situations where you won't have a working :mod:`readline` module:
186
200
187 * If you are using the built-in Python on Mac OS X.
201 * If you are using the built-in Python on Mac OS X.
188
202
189 * If you are running Windows, which doesn't have a :mod:`readline` module.
203 * If you are running Windows, which doesn't have a :mod:`readline` module.
190
204
191 When IPython is installed with :mod:`setuptools`, (e.g. with `easy_install`),
205 When IPython is installed with :mod:`setuptools`, (e.g. with `easy_install`),
192 readline is added as a dependency on OS X, and PyReadline on Windows, and will
206 readline is added as a dependency on OS X, and PyReadline on Windows, and will
193 be installed on your system. However, if you do not use setuptools, you may
207 be installed on your system. However, if you do not use setuptools, you may
194 have to install one of these packages yourself.
208 have to install one of these packages yourself.
195
209
196 On OS X, the built-in Python doesn't not have :mod:`readline` because of
210 On OS X, the built-in Python doesn't not have :mod:`readline` because of
197 license issues. Starting with OS X 10.5 (Leopard), Apple's built-in Python has
211 license issues. Starting with OS X 10.5 (Leopard), Apple's built-in Python has
198 a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9,
212 a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9,
199 many of the issues related to the differences between readline and libedit seem
213 many of the issues related to the differences between readline and libedit seem
200 to have been resolved. While you may find libedit sufficient, we have
214 to have been resolved. While you may find libedit sufficient, we have
201 occasional reports of bugs with it and several developers who use OS X as their
215 occasional reports of bugs with it and several developers who use OS X as their
202 main environment consider libedit unacceptable for productive, regular use with
216 main environment consider libedit unacceptable for productive, regular use with
203 IPython.
217 IPython.
204
218
205 Therefore, we *strongly* recommend that on OS X you get the full
219 Therefore, we *strongly* recommend that on OS X you get the full
206 :mod:`readline` module. We will *not* consider completion/history problems to
220 :mod:`readline` module. We will *not* consider completion/history problems to
207 be bugs for IPython if you are using libedit.
221 be bugs for IPython if you are using libedit.
208
222
209 To get a working :mod:`readline` module, just do (with :mod:`setuptools`
223 To get a working :mod:`readline` module, just do (with :mod:`setuptools`
210 installed):
224 installed):
211
225
212 .. code-block:: bash
226 .. code-block:: bash
213
227
214 $ easy_install readline
228 $ easy_install readline
215
229
216 .. note::
230 .. note::
217
231
218 Other Python distributions on OS X (such as fink, MacPorts and the official
232 Other Python distributions on OS X (such as fink, MacPorts and the official
219 python.org binaries) already have readline installed so you likely don't
233 python.org binaries) already have readline installed so you likely don't
220 have to do this step.
234 have to do this step.
221
235
222 If needed, the readline egg can be build and installed from source (see the
236 If needed, the readline egg can be build and installed from source (see the
223 wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
237 wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
224
238
225 On Windows, you will need the PyReadline module. PyReadline is a separate,
239 On Windows, you will need the PyReadline module. PyReadline is a separate,
226 Windows only implementation of readline that uses native Windows calls through
240 Windows only implementation of readline that uses native Windows calls through
227 :mod:`ctypes`. The easiest way of installing PyReadline is you use the binary
241 :mod:`ctypes`. The easiest way of installing PyReadline is you use the binary
228 installer available `here <https://launchpad.net/pyreadline/+download>`_.
242 installer available `here <https://launchpad.net/pyreadline/+download>`_.
229
243
230 nose
244 nose
231 ----
245 ----
232
246
233 To run the IPython test suite you will need the :mod:`nose` package. Nose
247 To run the IPython test suite you will need the :mod:`nose` package. Nose
234 provides a great way of sniffing out and running all of the IPython tests. The
248 provides a great way of sniffing out and running all of the IPython tests. The
235 simplest way of getting nose, is to use :command:`easy_install`:
249 simplest way of getting nose, is to use :command:`easy_install`:
236
250
237 .. code-block:: bash
251 .. code-block:: bash
238
252
239 $ easy_install nose
253 $ easy_install nose
240
254
241 Another way of getting this is to do:
255 Another way of getting this is to do:
242
256
243 .. code-block:: bash
257 .. code-block:: bash
244
258
245 $ easy_install ipython[test]
259 $ easy_install ipython[test]
246
260
247 For more installation options, see the `nose website
261 For more installation options, see the `nose website
248 <http://somethingaboutorange.com/mrl/projects/nose/>`_.
262 <http://somethingaboutorange.com/mrl/projects/nose/>`_.
249
263
250 .. warning::
264 .. warning::
251
265
252 As described above, the :command:`iptest` command currently doesn't work.
266 As described above, the :command:`iptest` command currently doesn't work.
253
267
254 Once you have nose installed, you can run IPython's test suite using the
268 Once you have nose installed, you can run IPython's test suite using the
255 iptest command:
269 iptest command:
256
270
257 .. code-block:: bash
271 .. code-block:: bash
258
272
259 $ iptest
273 $ iptest
260
274
261 pexpect
275 pexpect
262 -------
276 -------
263
277
264 The pexpect package is used in IPython's :command:`irunner` script, as well as
278 The pexpect package is used in IPython's :command:`irunner` script, as well as
265 for managing subprocesses [pexpect]_. IPython now includes a version of pexpect
279 for managing subprocesses [pexpect]_. IPython now includes a version of pexpect
266 in :mod:`IPython.external`, but if you have installed pexpect, IPython will use
280 in :mod:`IPython.external`, but if you have installed pexpect, IPython will use
267 that instead. On Unix platforms (including OS X), just do:
281 that instead. On Unix platforms (including OS X), just do:
268
282
269 .. code-block:: bash
283 .. code-block:: bash
270
284
271 $ easy_install pexpect
285 $ easy_install pexpect
272
286
273 Windows users are out of luck as pexpect does not run there.
287 Windows users are out of luck as pexpect does not run there.
274
288
275 Dependencies for IPython.parallel (parallel computing)
289 Dependencies for IPython.parallel (parallel computing)
276 ======================================================
290 ======================================================
277
291
278 :mod:`IPython.kernel` has been replaced by :mod:`IPython.parallel`,
292 :mod:`IPython.kernel` has been replaced by :mod:`IPython.parallel`,
279 which uses ZeroMQ for all communication.
293 which uses ZeroMQ for all communication.
280
294
281 IPython.parallel provides a nice architecture for parallel computing. The
295 IPython.parallel provides a nice architecture for parallel computing. The
282 main focus of this architecture is on interactive parallel computing. These
296 main focus of this architecture is on interactive parallel computing. These
283 features require just one package: pyzmq. See the next section for pyzmq
297 features require just one package: pyzmq. See the next section for pyzmq
284 details.
298 details.
285
299
286 On a Unix style platform (including OS X), if you want to use
300 On a Unix style platform (including OS X), if you want to use
287 :mod:`setuptools`, you can just do:
301 :mod:`setuptools`, you can just do:
288
302
289 .. code-block:: bash
303 .. code-block:: bash
290
304
291 $ easy_install ipython[zmq] # will include pyzmq
305 $ easy_install ipython[zmq] # will include pyzmq
292
306
293 Security in IPython.parallel is provided by SSH tunnels. By default, Linux
307 Security in IPython.parallel is provided by SSH tunnels. By default, Linux
294 and OSX clients will use the shell ssh command, but on Windows, we also
308 and OSX clients will use the shell ssh command, but on Windows, we also
295 support tunneling with paramiko [paramiko]_.
309 support tunneling with paramiko [paramiko]_.
296
310
297 Dependencies for IPython.zmq
311 Dependencies for IPython.zmq
298 ============================
312 ============================
299
313
300 pyzmq
314 pyzmq
301 -----
315 -----
302
316
303 IPython 0.11 introduced some new functionality, including a two-process
317 IPython 0.11 introduced some new functionality, including a two-process
304 execution model using ZeroMQ for communication [ZeroMQ]_. The Python bindings
318 execution model using ZeroMQ for communication [ZeroMQ]_. The Python bindings
305 to ZeroMQ are found in the pyzmq project, which is easy_install-able once you
319 to ZeroMQ are found in the pyzmq project, which is easy_install-able once you
306 have ZeroMQ installed. If you are on Python 2.6 or 2.7 on OSX, or 2.7 on Windows,
320 have ZeroMQ installed. If you are on Python 2.6 or 2.7 on OSX, or 2.7 on Windows,
307 pyzmq has eggs that include ZeroMQ itself.
321 pyzmq has eggs that include ZeroMQ itself.
308
322
309 IPython.zmq depends on pyzmq >= 2.1.4.
323 IPython.zmq depends on pyzmq >= 2.1.4.
310
324
311 Dependencies for ipython-qtconsole (new GUI)
325 Dependencies for ipython-qtconsole (new GUI)
312 ============================================
326 ============================================
313
327
314 PyQt
328 PyQt
315 ----
329 ----
316
330
317 Also with 0.11, a new GUI was added using the work in :mod:`IPython.zmq`,
331 Also with 0.11, a new GUI was added using the work in :mod:`IPython.zmq`,
318 which can be launched with ``ipython-qtconsole``. The GUI is built on PyQt ,
332 which can be launched with ``ipython-qtconsole``. The GUI is built on PyQt ,
319 which can be installed from the
333 which can be installed from the
320 `PyQt website <http://www.riverbankcomputing.co.uk/>`_.
334 `PyQt website <http://www.riverbankcomputing.co.uk/>`_.
321
335
322 pygments
336 pygments
323 --------
337 --------
324
338
325 The syntax-highlighting in ``ipython-qtconsole`` is done with the pygments project,
339 The syntax-highlighting in ``ipython-qtconsole`` is done with the pygments project,
326 which is easy_install-able [pygments]_.
340 which is easy_install-able [pygments]_.
327
341
328 .. [ZeroMQ] ZeroMQ. http://www.zeromq.org
342 .. [ZeroMQ] ZeroMQ. http://www.zeromq.org
329 .. [paramiko] paramiko. https://github.com/robey/paramiko
343 .. [paramiko] paramiko. https://github.com/robey/paramiko
330 .. [pygments] Pygments syntax highlighting. http://pygments.org
344 .. [pygments] Pygments syntax highlighting. http://pygments.org
331 .. [pexpect] Pexpect. http://www.noah.org/wiki/Pexpect
345 .. [pexpect] Pexpect. http://www.noah.org/wiki/Pexpect
General Comments 0
You need to be logged in to leave comments. Login now