##// END OF EJS Templates
update install doc...
Min RK -
Show More
@@ -2,29 +2,27 b' IPython requires Python 2.7 or \xe2\x89\xa5 3.3.'
2 2
3 3 .. note::
4 4
5 If you need to use Python 2.6 or 3.2, you can find IPython 1.0
6 `here <http://archive.ipython.org/release/>`__.
5 If you need to use Python 2.6 or 3.2, you can find IPython 1.x
6 `here <http://archive.ipython.org/release/>`__,
7 or get it with pip::
8
9 pip install 'ipython<2'
10
7 11
8 12 Quickstart
9 13 ==========
10 14
11 If you have :mod:`setuptools`,
15 If you have :mod:`pip`,
12 16 the quickest way to get up and running with IPython is:
13 17
14 18 .. code-block:: bash
15 19
16 20 $ pip install "ipython[all]"
17 21
18 This will download and install IPython and its main optional dependencies:
19
20 - jinja2, needed for the notebook
21 - sphinx, needed for nbconvert
22 - pyzmq, needed for IPython's parallel computing features, qt console and
23 notebook
24 - pygments, used by nbconvert and the Qt console for syntax highlighting
25 - tornado, needed by the web-based notebook
26 - nose, used by the test suite
27 - readline (on OS X) or pyreadline (on Windows), needed for the terminal
22 This will download and install IPython and its main optional dependencies for the notebook,
23 qtconsole, tests, and other functionality.
24 Some dependencies (Qt, PyQt for the QtConsole, pandoc for nbconvert) are not pip-installable,
25 and will not be pulled in by pip.
28 26
29 27 To run IPython's test suite, use the :command:`iptest` command:
30 28
@@ -53,11 +51,6 b' In many scenarios, this is the simplest method of installing Python packages.'
53 51 More information about :mod:`pip` can be found on
54 52 `its PyPI page <http://pypi.python.org/pypi/pip>`__.
55 53
56 .. note::
57
58 On Windows, IPython *requires* :mod:`setuptools`. We hope to
59 change this in the future, but for now on Windows, you *must* install
60 :mod:`setuptools` to use IPython.
61 54
62 55 More general information about installing Python packages can be found in
63 56 `Python's documentation <http://docs.python.org>`_.
@@ -71,15 +64,14 b' with no external dependencies. However, some Python distributions'
71 64 (particularly on Windows and OS X), don't come with a working :mod:`readline`
72 65 module. The IPython shell will work without :mod:`readline`, but will lack
73 66 many features that users depend on, such as tab completion and command line
74 editing. If you install IPython with :mod:`setuptools`, (e.g. with
75 `pip`), then the appropriate :mod:`readline` for your platform will be
76 installed. See below for details of how to make sure you have a working
77 :mod:`readline`.
67 editing. If you install IPython with :mod:`pip`,
68 then the appropriate :mod:`readline` for your platform will be installed.
69 See below for details of how to make sure you have a working :mod:`readline`.
78 70
79 71 Installation using pip
80 72 ----------------------
81 73
82 If you have :mod:`setuptools` or :mod:`pip`, the easiest way of getting IPython is
74 If you have :mod:`pip`, the easiest way of getting IPython is
83 75 to simply use :command:`pip`:
84 76
85 77 .. code-block:: bash
@@ -93,7 +85,7 b' Installation from source'
93 85 ------------------------
94 86
95 87 If you don't want to use :command:`pip`, or don't have it installed,
96 just grab the latest stable build of IPython from `here
88 grab the latest stable build of IPython from `here
97 89 <http://ipython.org/download.html>`_. Then do the following:
98 90
99 91 .. code-block:: bash
@@ -108,39 +100,20 b' permissions, you may need to run the last command with :command:`sudo`.'
108 100 Windows
109 101 -------
110 102
111 As mentioned above, on Windows, IPython requires :mod:`setuptools`, and it also
112 requires the PyReadline library to properly support coloring and keyboard
103 As mentioned above, terminal IPython requires the PyReadline library to properly support coloring and keyboard
113 104 management (features that the default windows console doesn't have). So on
114 105 Windows, the installation procedure is:
115 106
116 1. Install `setuptools <http://pypi.python.org/pypi/setuptools>`_.
117
118 2. Install `pyreadline <http://pypi.python.org/pypi/pyreadline>`_. You can use
119 the command ``pip install pyreadline`` from a terminal, or the binary
120 installer appropriate for your platform from the PyPI page.
121
122 3. Install IPython itself, which you can download from `PyPI
123 <http://pypi.python.org/pypi/ipython>`_ or from `our site
124 <http://ipython.org/download.html>`_. Note that on Windows 7, you *must*
125 right-click and 'Run as administrator' for the Start menu shortcuts to be
126 created.
107 1. Install `pip <http://pypi.python.org/pypi/pip>`_, if you don't have it already.
108 2. Install IPython: ``pip install ipython``.
127 109
128 IPython by default runs in a terminal window, but the normal terminal
129 application supplied by Microsoft Windows is very primitive. You may want to
130 download the excellent and free Console_ application instead, which is a far
131 superior tool. You can even configure Console to give you by default an
132 IPython tab, which is very convenient to create new IPython sessions directly
133 from the working terminal.
134 110
135 .. _Console: http://sourceforge.net/projects/console
136
137
138 111 Installing the development version
139 112 ----------------------------------
140 113
141 114 It is also possible to install the development version of IPython from our
142 115 `Git <http://git-scm.com/>`_ source code repository. To do this you will
143 need to have Git installed on your system. Then just do:
116 need to have Git installed on your system. Then do:
144 117
145 118 .. code-block:: bash
146 119
@@ -149,18 +122,16 b' need to have Git installed on your system. Then just do:'
149 122 $ python setup.py install
150 123
151 124 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
153 step by:
125 you have :mod:`pip`, you can replace the last step by:
154 126
155 127 .. code-block:: bash
156 128
157 $ python setupegg.py develop
129 $ pip install -e .
158 130
159 131 This creates links in the right places and installs the command line script to
160 132 the appropriate places.
161 133
162 Then, if you want to update your IPython at any time,
163 just do:
134 Then, if you want to update your IPython at any time, do:
164 135
165 136 .. code-block:: bash
166 137
@@ -191,6 +162,7 b' get. These are:'
191 162
192 163 * readline (for command line editing, tab completion, etc.)
193 164 * nose (to run the IPython test suite)
165 * mock (Python < 3, also for tests)
194 166
195 167 If you are comfortable installing these things yourself, have at it, otherwise
196 168 read on for more details.
@@ -209,7 +181,7 b' native Windows calls through :mod:`ctypes`. The easiest way of installing'
209 181 PyReadline is you use the binary installer available `here
210 182 <http://pypi.python.org/pypi/pyreadline>`__.
211 183
212 On OSX, if you are using the built-in Python shipped by Apple, you will be
184 On OS X, if you are using the built-in Python shipped by Apple, you will be
213 185 missing a proper readline implementation as Apple ships instead a library called
214 186 ``libedit`` that provides only some of readline's functionality. While you may
215 187 find libedit sufficient, we have occasional reports of bugs with it and several
@@ -219,7 +191,7 b' for productive, regular use with IPython.'
219 191 Therefore, IPython on OS X depends on the :mod:`gnureadline` module.
220 192 We will *not* consider completion/history problems to be bugs for IPython if you are using libedit.
221 193
222 To get a working :mod:`readline` module on OS X, just do (with :mod:`pip`
194 To get a working :mod:`readline` module on OS X, do (with :mod:`pip`
223 195 installed):
224 196
225 197 .. code-block:: bash
@@ -231,7 +203,7 b' installed):'
231 203 Other Python distributions on OS X (such as Anaconda, fink, MacPorts)
232 204 already have proper readline so you likely don't have to do this step.
233 205
234 When IPython is installed with :mod:`setuptools`, (e.g. using the
206 When IPython is installed with :mod:`pip`, (e.g. using the
235 207 ``pip`` command), the correct readline should be installed if you specify the `terminal`
236 208 optional dependencies:
237 209
@@ -270,84 +242,67 b' iptest command:'
270 242 Dependencies for IPython.parallel (parallel computing)
271 243 ======================================================
272 244
273 IPython.parallel provides a nice architecture for parallel computing, with a
274 focus on fluid interactive workflows. These features require just one package:
275 PyZMQ. See the next section for PyZMQ details.
245 IPython's inter-process communication uses the PyZMQ_ bindings for the ZeroMQ_ messaging library.
246 This is the only dependency for :mod:`IPython.parallel`.
276 247
277 On a Unix style platform (including OS X), if you want to use
278 :mod:`setuptools`, you can just do:
248 Shortcut:
279 249
280 250 .. code-block:: bash
281 251
282 $ pip install "ipython[zmq]" # will include pyzmq
252 pip install "ipython[parallel]"
283 253
284 Security in IPython.parallel is provided by SSH tunnels. By default, Linux
285 and OSX clients will use the shell ssh command, but on Windows, we also
286 support tunneling with paramiko_.
254 or manual
287 255
288 Dependencies for IPython.kernel.zmq
289 ===================================
256 .. code-block:: bash
290 257
291 pyzmq
292 -----
258 pip install pyzmq
293 259
294 IPython 0.11 introduced some new functionality, including a two-process
295 execution model using ZeroMQ_ for communication. The Python bindings to ZeroMQ
296 are found in the PyZMQ_ project, which is pip install-able.
297 If you are on Python 2.7, 3.3, or 3.4 on OSX or Windows,
298 pyzmq has eggs and wheels that include ZeroMQ itself.
260 PyZMQ provides wheels for current Python on OS X and Windows, so installing pyzmq will typically not require compilation.
299 261
300 IPython.kernel.zmq depends on pyzmq >= 2.2.
262 IPython.parallel can use SSH tunnels, which require paramiko_ on Windows.
301 263
302 Dependencies for the IPython QT console
264 Dependencies for the IPython Qt console
303 265 =======================================
304 266
305 pyzmq
306 -----
267 pyzmq_, pygments_, PyQt_ (or PySide_)
307 268
308 Like the :mod:`IPython.parallel` package, the QT Console requires ZeroMQ and
309 PyZMQ.
269 Shortcut:
310 270
311 Qt
312 --
271 .. code-block:: bash
313 272
314 Also with 0.11, a new GUI was added using the work in :mod:`IPython.kernel.zmq`, which
315 can be launched with ``ipython qtconsole``. The GUI is built on Qt, and works
316 with either `PyQt <http://www.riverbankcomputing.co.uk/>`_, or `PySide
317 <http://qt-project.org/wiki/PySide>`_.
273 pip install "ipython[qtconsole]"
318 274
319 pygments
320 --------
275 or manual
276
277 .. code-block:: bash
278
279 pip install pyzmq pygments
321 280
322 The syntax-highlighting in ``ipython qtconsole`` is done with the pygments_
323 project, which is pip install-able.
281 PyQt/PySide are not pip installable, so generally must be installed via system package managers (or conda).
324 282
325 283 .. _installnotebook:
326 284
327 285 Dependencies for the IPython HTML notebook
328 286 ==========================================
329 287
330 The IPython notebook is a notebook-style web interface to IPython and can be
331 started with the command ``ipython notebook``.
288 The HTML notebook is a complex web application with quite a few dependencies:
332 289
333 pyzmq
334 -----
290 pyzmq_, jinja2_, tornado_, mistune_, jsonschema_, pygments_, terminado_
335 291
336 Like the :mod:`IPython.parallel` and :mod:`IPython.frontend.qt.console`
337 packages, the HTML notebook requires ZeroMQ and PyZMQ.
292 Shortcut:
338 293
339 Tornado
340 -------
294 .. code-block:: bash
341 295
342 The IPython notebook uses the Tornado_ project for its HTTP server. Tornado 2.1
343 is required, in order to support current versions of browsers, due to an update
344 to the websocket protocol.
296 pip install "ipython[notebook]"
345 297
346 Jinja
347 -----
298 or manual:
348 299
349 The IPython notebook uses the Jinja_ templating tool to render HTML pages.
300 .. code-block:: bash
350 301
302 pip install pyzmq jinja2 tornado mistune jsonschema pygments terminado_
303
304 The IPython notebook is a notebook-style web interface to IPython and can be
305 started with the command ``ipython notebook``.
351 306
352 307 MathJax
353 308 -------
@@ -360,20 +315,19 b' you can install MathJax locally.'
360 315
361 316 A quick and easy method is to install it from a python session::
362 317
363 from IPython.external.mathjax import install_mathjax
364 install_mathjax()
318 python -m IPython.external.mathjax
365 319
366 320 If you need tighter configuration control, you can download your own copy
367 321 of MathJax from http://www.mathjax.org/download/ - use the MathJax-2.0 link.
368 322 When you have the file stored locally, install it with::
369 323
370 python -m IPython.external.mathjax /path/to/source/mathjax-MathJax-v2.0-20-g07669ac.zip
324 python -m IPython.external.mathjax /path/to/source/mathjax-MathJax-v2.0-20-g07669ac.zip
371 325
372 326 For unusual needs, IPython can tell you what directory it wants to find MathJax in::
373 327
374 python -m IPython.external.mathjax -d /some/other/mathjax
328 python -m IPython.external.mathjax -d /some/other/mathjax
375 329
376 By default Mathjax will be installed in your ipython profile directory, but you
330 By default Mathjax will be installed in your ipython directory, but you
377 331 can make system wide install, please refer to the documentation and helper function
378 332 of :mod:`IPython.external.mathjax`
379 333
@@ -395,6 +349,7 b' The following browsers are unsupported:'
395 349 * Chrome < 13
396 350 * Opera (any): CSS issues, but execution might work
397 351 * Internet Explorer < 10
352 * Internet Explorer ≥ 10 (same as Opera)
398 353
399 354 The following specific combinations are known **NOT** to work:
400 355
@@ -409,11 +364,7 b' expect there will be some CSS issues related to the flexible box model.'
409 364 Dependencies for nbconvert (converting notebooks to various formats)
410 365 ====================================================================
411 366
412 pandoc
413 ------
414
415 The most important dependency of nbconvert is Pandoc_ 1.10 or later, a document format translation program.
416 This is not a Python package, so it cannot be expressed as a regular IPython dependency with setuptools.
367 For converting markdown to formats other than HTML, nbconvert uses Pandoc_ (1.12.1 or later).
417 368
418 369 To install pandoc on Linux, you can generally use your package manager::
419 370
@@ -432,3 +383,9 b' On other platforms, you can get pandoc from `their website <http://johnmacfarlan'
432 383 .. _pandoc: http://johnmacfarlane.net/pandoc
433 384 .. _Tornado: http://www.tornadoweb.org
434 385 .. _MathJax: http://www.mathjax.org
386 .. _PyQt: http://www.riverbankcomputing.com/software/pyqt/intro
387 .. _PySide: http://qt-project.org/wiki/PySide
388 .. _jinja2: http://jinja.pocoo.org/
389 .. _mistune: https://github.com/lepture/mistune
390 .. _jsonschema: https://github.com/Julian/jsonschema
391 .. _terminado: https://github.com/takluyver/terminado No newline at end of file
General Comments 0
You need to be logged in to leave comments. Login now