##// END OF EJS Templates
omit Nokia, update pyside link, closes #6166...
Paul Ivanov -
Show More
@@ -1,435 +1,434 b''
1 1 IPython requires Python 2.7 or ≥ 3.3.
2 2
3 3 .. note::
4 4
5 5 If you need to use Python 2.6 or 3.2, you can find IPython 1.0
6 6 `here <http://archive.ipython.org/release/>`__.
7 7
8 8 Quickstart
9 9 ==========
10 10
11 11 If you have :mod:`setuptools`,
12 12 the quickest way to get up and running with IPython is:
13 13
14 14 .. code-block:: bash
15 15
16 16 $ pip install ipython[all]
17 17
18 18 This will download and install IPython and its main optional dependencies:
19 19
20 20 - jinja2, needed for the notebook
21 21 - sphinx, needed for nbconvert
22 22 - pyzmq, needed for IPython's parallel computing features, qt console and
23 23 notebook
24 24 - pygments, used by nbconvert and the Qt console for syntax highlighting
25 25 - tornado, needed by the web-based notebook
26 26 - nose, used by the test suite
27 27 - readline (on OS X) or pyreadline (on Windows), needed for the terminal
28 28
29 29 To run IPython's test suite, use the :command:`iptest` command:
30 30
31 31 .. code-block:: bash
32 32
33 33 $ iptest
34 34
35 35
36 36 Overview
37 37 ========
38 38
39 39 This document describes in detail the steps required to install IPython,
40 40 and its various optional dependencies.
41 41 For a few quick ways to get started with package managers or full Python distributions,
42 42 see `the install page <http://ipython.org/install.html>`_ of the IPython website.
43 43
44 44 IPython is organized into a number of subpackages, each of which has its own dependencies.
45 45 All of the subpackages come with IPython, so you don't need to download and
46 46 install them separately. However, to use a given subpackage, you will need to
47 47 install all of its dependencies.
48 48
49 49 Please let us know if you have problems installing IPython or any of its dependencies.
50 50
51 51 IPython and most dependencies can be installed via :command:`pip`.
52 52 In many scenarios, this is the simplest method of installing Python packages.
53 53 More information about :mod:`pip` can be found on
54 54 `its PyPI page <http://pypi.python.org/pypi/pip>`__.
55 55
56 56 .. note::
57 57
58 58 On Windows, IPython *requires* :mod:`setuptools`. We hope to
59 59 change this in the future, but for now on Windows, you *must* install
60 60 :mod:`setuptools` to use IPython.
61 61
62 62 More general information about installing Python packages can be found in
63 63 `Python's documentation <http://docs.python.org>`_.
64 64
65 65
66 66 Installing IPython itself
67 67 =========================
68 68
69 69 Given a properly built Python, the basic interactive IPython shell will work
70 70 with no external dependencies. However, some Python distributions
71 71 (particularly on Windows and OS X), don't come with a working :mod:`readline`
72 72 module. The IPython shell will work without :mod:`readline`, but will lack
73 73 many features that users depend on, such as tab completion and command line
74 74 editing. If you install IPython with :mod:`setuptools`, (e.g. with
75 75 `pip`), then the appropriate :mod:`readline` for your platform will be
76 76 installed. See below for details of how to make sure you have a working
77 77 :mod:`readline`.
78 78
79 79 Installation using pip
80 80 ----------------------
81 81
82 82 If you have :mod:`setuptools` or :mod:`pip`, the easiest way of getting IPython is
83 83 to simply use :command:`pip`:
84 84
85 85 .. code-block:: bash
86 86
87 87 $ pip install ipython
88 88
89 89 That's it.
90 90
91 91
92 92 Installation from source
93 93 ------------------------
94 94
95 95 If you don't want to use :command:`pip`, or don't have it installed,
96 96 just grab the latest stable build of IPython from `here
97 97 <http://ipython.org/download.html>`_. Then do the following:
98 98
99 99 .. code-block:: bash
100 100
101 101 $ tar -xzf ipython.tar.gz
102 102 $ cd ipython
103 103 $ python setup.py install
104 104
105 105 If you are installing to a location (like ``/usr/local``) that requires higher
106 106 permissions, you may need to run the last command with :command:`sudo`.
107 107
108 108 Windows
109 109 -------
110 110
111 111 As mentioned above, on Windows, IPython requires :mod:`setuptools`, and it also
112 112 requires the PyReadline library to properly support coloring and keyboard
113 113 management (features that the default windows console doesn't have). So on
114 114 Windows, the installation procedure is:
115 115
116 116 1. Install `setuptools <http://pypi.python.org/pypi/setuptools>`_.
117 117
118 118 2. Install `pyreadline <http://pypi.python.org/pypi/pyreadline>`_. You can use
119 119 the command ``pip install pyreadline`` from a terminal, or the binary
120 120 installer appropriate for your platform from the PyPI page.
121 121
122 122 3. Install IPython itself, which you can download from `PyPI
123 123 <http://pypi.python.org/pypi/ipython>`_ or from `our site
124 124 <http://ipython.org/download.html>`_. Note that on Windows 7, you *must*
125 125 right-click and 'Run as administrator' for the Start menu shortcuts to be
126 126 created.
127 127
128 128 IPython by default runs in a terminal window, but the normal terminal
129 129 application supplied by Microsoft Windows is very primitive. You may want to
130 130 download the excellent and free Console_ application instead, which is a far
131 131 superior tool. You can even configure Console to give you by default an
132 132 IPython tab, which is very convenient to create new IPython sessions directly
133 133 from the working terminal.
134 134
135 135 .. _Console: http://sourceforge.net/projects/console
136 136
137 137
138 138 Installing the development version
139 139 ----------------------------------
140 140
141 141 It is also possible to install the development version of IPython from our
142 142 `Git <http://git-scm.com/>`_ source code repository. To do this you will
143 143 need to have Git installed on your system. Then just do:
144 144
145 145 .. code-block:: bash
146 146
147 147 $ git clone --recursive https://github.com/ipython/ipython.git
148 148 $ cd ipython
149 149 $ python setup.py install
150 150
151 151 Some users want to be able to follow the development branch as it changes. If
152 152 you have :mod:`setuptools` installed, this is easy. Simply replace the last
153 153 step by:
154 154
155 155 .. code-block:: bash
156 156
157 157 $ python setupegg.py develop
158 158
159 159 This creates links in the right places and installs the command line script to
160 160 the appropriate places.
161 161
162 162 Then, if you want to update your IPython at any time,
163 163 just do:
164 164
165 165 .. code-block:: bash
166 166
167 167 $ git pull
168 168
169 169 IPython now uses git submodules to ship its javascript dependencies. If you run
170 170 IPython from git master, you may need to update submodules once in a while with:
171 171
172 172 .. code-block:: bash
173 173
174 174 $ git submodule update
175 175
176 176 or
177 177
178 178 .. code-block:: bash
179 179
180 180 $ python setup.py submodule
181 181
182 182 Another option is to copy `git hooks <https://github.com/ipython/ipython/tree/master/git-hooks>`_
183 183 to your ``./git/hooks/`` directory to ensure that your submodules are up to date on each pull.
184 184
185 185
186 186 Basic optional dependencies
187 187 ===========================
188 188
189 189 There are a number of basic optional dependencies that most users will want to
190 190 get. These are:
191 191
192 192 * readline (for command line editing, tab completion, etc.)
193 193 * nose (to run the IPython test suite)
194 194
195 195 If you are comfortable installing these things yourself, have at it, otherwise
196 196 read on for more details.
197 197
198 198 IPython uses several other modules, such as pexpect_ and path.py, if they are
199 199 installed on your system, but it can also use bundled versions from
200 200 :mod:`IPython.external`, so there's no need to install them separately.
201 201
202 202 readline
203 203 --------
204 204
205 205 As indicated above, on Windows, to get full functionality in the console
206 206 version of IPython, PyReadline is needed.
207 207 PyReadline is a separate, Windows only implementation of readline that uses
208 208 native Windows calls through :mod:`ctypes`. The easiest way of installing
209 209 PyReadline is you use the binary installer available `here
210 210 <http://pypi.python.org/pypi/pyreadline>`__.
211 211
212 212 On OSX, if you are using the built-in Python shipped by Apple, you will be
213 213 missing a proper readline implementation as Apple ships instead a library called
214 214 ``libedit`` that provides only some of readline's functionality. While you may
215 215 find libedit sufficient, we have occasional reports of bugs with it and several
216 216 developers who use OS X as their main environment consider libedit unacceptable
217 217 for productive, regular use with IPython.
218 218
219 219 Therefore, IPython on OS X depends on the :mod:`gnureadline` module.
220 220 We will *not* consider completion/history problems to be bugs for IPython if you are using libedit.
221 221
222 222 To get a working :mod:`readline` module on OS X, just do (with :mod:`pip`
223 223 installed):
224 224
225 225 .. code-block:: bash
226 226
227 227 $ pip install gnureadline
228 228
229 229 .. note::
230 230
231 231 Other Python distributions on OS X (such as Anaconda, fink, MacPorts)
232 232 already have proper readline so you likely don't have to do this step.
233 233
234 234 When IPython is installed with :mod:`setuptools`, (e.g. using the
235 235 ``pip`` command), the correct readline should be installed if you specify the `terminal`
236 236 optional dependencies:
237 237
238 238 .. code-block:: bash
239 239
240 240 $ pip install ipython[terminal]
241 241
242 242
243 243 nose
244 244 ----
245 245
246 246 To run the IPython test suite you will need the :mod:`nose` package. Nose
247 247 provides a great way of sniffing out and running all of the IPython tests. The
248 248 simplest way of getting nose is to use :command:`pip`:
249 249
250 250 .. code-block:: bash
251 251
252 252 $ pip install nose
253 253
254 254 Another way of getting this is to do:
255 255
256 256 .. code-block:: bash
257 257
258 258 $ pip install ipython[test]
259 259
260 260 For more installation options, see the `nose website
261 261 <http://somethingaboutorange.com/mrl/projects/nose/>`_.
262 262
263 263 Once you have nose installed, you can run IPython's test suite using the
264 264 iptest command:
265 265
266 266 .. code-block:: bash
267 267
268 268 $ iptest
269 269
270 270 Dependencies for IPython.parallel (parallel computing)
271 271 ======================================================
272 272
273 273 IPython.parallel provides a nice architecture for parallel computing, with a
274 274 focus on fluid interactive workflows. These features require just one package:
275 275 PyZMQ. See the next section for PyZMQ details.
276 276
277 277 On a Unix style platform (including OS X), if you want to use
278 278 :mod:`setuptools`, you can just do:
279 279
280 280 .. code-block:: bash
281 281
282 282 $ pip install ipython[zmq] # will include pyzmq
283 283
284 284 Security in IPython.parallel is provided by SSH tunnels. By default, Linux
285 285 and OSX clients will use the shell ssh command, but on Windows, we also
286 286 support tunneling with paramiko_.
287 287
288 288 Dependencies for IPython.kernel.zmq
289 289 ===================================
290 290
291 291 pyzmq
292 292 -----
293 293
294 294 IPython 0.11 introduced some new functionality, including a two-process
295 295 execution model using ZeroMQ_ for communication. The Python bindings to ZeroMQ
296 296 are found in the PyZMQ_ project, which is pip install-able.
297 297 If you are on Python 2.7, 3.3, or 3.4 on OSX or Windows,
298 298 pyzmq has eggs and wheels that include ZeroMQ itself.
299 299
300 300 IPython.kernel.zmq depends on pyzmq >= 2.2.
301 301
302 302 Dependencies for the IPython QT console
303 303 =======================================
304 304
305 305 pyzmq
306 306 -----
307 307
308 308 Like the :mod:`IPython.parallel` package, the QT Console requires ZeroMQ and
309 309 PyZMQ.
310 310
311 311 Qt
312 312 --
313 313
314 314 Also with 0.11, a new GUI was added using the work in :mod:`IPython.kernel.zmq`, which
315 315 can be launched with ``ipython qtconsole``. The GUI is built on Qt, and works
316 with either PyQt, which can be installed from the `PyQt website
317 <http://www.riverbankcomputing.co.uk/>`_, or `PySide
318 <http://www.pyside.org/>`_, from Nokia.
316 with either `PyQt <http://www.riverbankcomputing.co.uk/>`_, or `PySide
317 <http://qt-project.org/wiki/PySide>`_.
319 318
320 319 pygments
321 320 --------
322 321
323 322 The syntax-highlighting in ``ipython qtconsole`` is done with the pygments_
324 323 project, which is pip install-able.
325 324
326 325 .. _installnotebook:
327 326
328 327 Dependencies for the IPython HTML notebook
329 328 ==========================================
330 329
331 330 The IPython notebook is a notebook-style web interface to IPython and can be
332 331 started with the command ``ipython notebook``.
333 332
334 333 pyzmq
335 334 -----
336 335
337 336 Like the :mod:`IPython.parallel` and :mod:`IPython.frontend.qt.console`
338 337 packages, the HTML notebook requires ZeroMQ and PyZMQ.
339 338
340 339 Tornado
341 340 -------
342 341
343 342 The IPython notebook uses the Tornado_ project for its HTTP server. Tornado 2.1
344 343 is required, in order to support current versions of browsers, due to an update
345 344 to the websocket protocol.
346 345
347 346 Jinja
348 347 -----
349 348
350 349 The IPython notebook uses the Jinja_ templating tool to render HTML pages.
351 350
352 351
353 352 MathJax
354 353 -------
355 354
356 355 The IPython notebook uses the MathJax_ Javascript library for rendering LaTeX
357 356 in web browsers. Because MathJax is large, we don't include it with
358 357 IPython. Normally IPython will load MathJax from a CDN, but if you have a slow
359 358 network connection, or want to use LaTeX without an internet connection at all,
360 359 you can install MathJax locally.
361 360
362 361 A quick and easy method is to install it from a python session::
363 362
364 363 from IPython.external.mathjax import install_mathjax
365 364 install_mathjax()
366 365
367 366 If you need tighter configuration control, you can download your own copy
368 367 of MathJax from http://www.mathjax.org/download/ - use the MathJax-2.0 link.
369 368 When you have the file stored locally, install it with::
370 369
371 370 python -m IPython.external.mathjax /path/to/source/mathjax-MathJax-v2.0-20-g07669ac.zip
372 371
373 372 For unusual needs, IPython can tell you what directory it wants to find MathJax in::
374 373
375 374 python -m IPython.external.mathjax -d /some/other/mathjax
376 375
377 376 By default Mathjax will be installed in your ipython profile directory, but you
378 377 can make system wide install, please refer to the documentation and helper function
379 378 of :mod:`IPython.external.mathjax`
380 379
381 380 Browser Compatibility
382 381 ---------------------
383 382
384 383 The IPython notebook is officially supported on the following browsers:
385 384
386 385 * Chrome ≥ 13
387 386 * Safari ≥ 5
388 387 * Firefox ≥ 6
389 388
390 389 The is mainly due to the notebook's usage of WebSockets and the flexible box model.
391 390
392 391 The following browsers are unsupported:
393 392
394 393 * Safari < 5
395 394 * Firefox < 6
396 395 * Chrome < 13
397 396 * Opera (any): CSS issues, but execution might work
398 397 * Internet Explorer < 10
399 398
400 399 The following specific combinations are known **NOT** to work:
401 400
402 401 * Safari, IPython 0.12, tornado ≥ 2.2.0
403 402 * Safari with HTTPS connection to notebook and an untrusted certificate (websockets will fail)
404 403 * The `diigo Chrome extension <http://help.diigo.com/tools/chrome-extension>`_ seems to interfere with scrolling
405 404
406 405 There are some early reports that the Notebook works on Internet Explorer 10, but we
407 406 expect there will be some CSS issues related to the flexible box model.
408 407
409 408
410 409 Dependencies for nbconvert (converting notebooks to various formats)
411 410 ====================================================================
412 411
413 412 pandoc
414 413 ------
415 414
416 415 The most important dependency of nbconvert is Pandoc_ 1.10 or later, a document format translation program.
417 416 This is not a Python package, so it cannot be expressed as a regular IPython dependency with setuptools.
418 417
419 418 To install pandoc on Linux, you can generally use your package manager::
420 419
421 420 sudo apt-get install pandoc
422 421
423 422 On other platforms, you can get pandoc from `their website <http://johnmacfarlane.net/pandoc/installing.html>`_.
424 423
425 424
426 425 .. _ZeroMQ: http://www.zeromq.org
427 426 .. _PyZMQ: https://github.com/zeromq/pyzmq
428 427 .. _paramiko: https://github.com/robey/paramiko
429 428 .. _pygments: http://pygments.org
430 429 .. _pexpect: http://pexpect.readthedocs.org/en/latest/
431 430 .. _Jinja: http://jinja.pocoo.org
432 431 .. _Sphinx: http://sphinx-doc.org
433 432 .. _pandoc: http://johnmacfarlane.net/pandoc
434 433 .. _Tornado: http://www.tornadoweb.org
435 434 .. _MathJax: http://www.mathjax.org
General Comments 0
You need to be logged in to leave comments. Login now