Show More
@@ -1,12 +1,10 b'' | |||||
1 | IPython requires Python 2.7 or ≥ 3.3. |
|
1 | IPython requires Python 2.7 or ≥ 3.3. | |
2 |
|
2 | |||
3 | .. note:: |
|
3 | .. seealso:: | |
4 |
|
4 | |||
5 | If you need to use Python 2.6 or 3.2, you can find IPython 1.x |
|
5 | `Installing Jupyter <http://jupyter.readthedocs.org/en/latest/install.html>`__ | |
6 | `here <http://archive.ipython.org/release/>`__, |
|
6 | The Notebook, nbconvert, and many other former pieces of IPython are now | |
7 | or get it with pip:: |
|
7 | part of Project Jupyter. | |
8 |
|
||||
9 | pip install 'ipython<2' |
|
|||
10 |
|
8 | |||
11 |
|
9 | |||
12 | Quickstart |
|
10 | Quickstart | |
@@ -17,12 +15,10 b' the quickest way to get up and running with IPython is:' | |||||
17 |
|
15 | |||
18 | .. code-block:: bash |
|
16 | .. code-block:: bash | |
19 |
|
17 | |||
20 |
$ pip install |
|
18 | $ pip install ipython | |
21 |
|
19 | |||
22 | This will download and install IPython and its main optional dependencies for the notebook, |
|
20 | To use IPython with notebooks or the Qt console, you should also install | |
23 | qtconsole, tests, and other functionality. |
|
21 | ``jupyter``. | |
24 | Some dependencies (Qt, PyQt for the QtConsole, pandoc for nbconvert) are not pip-installable, |
|
|||
25 | and will not be pulled in by pip. |
|
|||
26 |
|
22 | |||
27 | To run IPython's test suite, use the :command:`iptest` command: |
|
23 | To run IPython's test suite, use the :command:`iptest` command: | |
28 |
|
24 | |||
@@ -34,16 +30,10 b" To run IPython's test suite, use the :command:`iptest` command:" | |||||
34 | Overview |
|
30 | Overview | |
35 | ======== |
|
31 | ======== | |
36 |
|
32 | |||
37 |
This document describes in detail the steps required to install IPython |
|
33 | This document describes in detail the steps required to install IPython. | |
38 | and its various optional dependencies. |
|
|||
39 | For a few quick ways to get started with package managers or full Python distributions, |
|
34 | For a few quick ways to get started with package managers or full Python distributions, | |
40 | see `the install page <http://ipython.org/install.html>`_ of the IPython website. |
|
35 | see `the install page <http://ipython.org/install.html>`_ of the IPython website. | |
41 |
|
36 | |||
42 | IPython is organized into a number of subpackages, each of which has its own dependencies. |
|
|||
43 | All of the subpackages come with IPython, so you don't need to download and |
|
|||
44 | install them separately. However, to use a given subpackage, you will need to |
|
|||
45 | install all of its dependencies. |
|
|||
46 |
|
||||
47 | Please let us know if you have problems installing IPython or any of its dependencies. |
|
37 | Please let us know if you have problems installing IPython or any of its dependencies. | |
48 |
|
38 | |||
49 | IPython and most dependencies can be installed via :command:`pip`. |
|
39 | IPython and most dependencies can be installed via :command:`pip`. | |
@@ -84,8 +74,8 b' Installation from source' | |||||
84 | ------------------------ |
|
74 | ------------------------ | |
85 |
|
75 | |||
86 | If you don't want to use :command:`pip`, or don't have it installed, |
|
76 | If you don't want to use :command:`pip`, or don't have it installed, | |
87 |
grab the latest stable |
|
77 | grab the latest stable tarball of IPython `from PyPI | |
88 |
<http://ipython.org/ |
|
78 | <https://pypi.python.org/pypi/ipython>`__. Then do the following: | |
89 |
|
79 | |||
90 | .. code-block:: bash |
|
80 | .. code-block:: bash | |
91 |
|
81 | |||
@@ -97,7 +87,6 b' If you are installing to a location (like ``/usr/local``) that requires higher' | |||||
97 | permissions, you may need to run the last command with :command:`sudo`. |
|
87 | permissions, you may need to run the last command with :command:`sudo`. | |
98 |
|
88 | |||
99 |
|
89 | |||
100 |
|
||||
101 | Installing the development version |
|
90 | Installing the development version | |
102 | ---------------------------------- |
|
91 | ---------------------------------- | |
103 |
|
92 | |||
@@ -127,51 +116,34 b' Then, if you want to update your IPython at any time, do:' | |||||
127 |
|
116 | |||
128 | $ git pull |
|
117 | $ git pull | |
129 |
|
118 | |||
130 | IPython now uses git submodules to ship its javascript dependencies. If you run |
|
119 | .. _dependencies: | |
131 | IPython from git master, you may need to update submodules once in a while with: |
|
|||
132 |
|
||||
133 | .. code-block:: bash |
|
|||
134 |
|
||||
135 | $ git submodule update |
|
|||
136 |
|
||||
137 | or |
|
|||
138 |
|
||||
139 | .. code-block:: bash |
|
|||
140 |
|
||||
141 | $ python setup.py submodule |
|
|||
142 |
|
||||
143 | Another option is to copy `git hooks <https://github.com/ipython/ipython/tree/master/git-hooks>`_ |
|
|||
144 | to your ``./git/hooks/`` directory to ensure that your submodules are up to date on each pull. |
|
|||
145 |
|
120 | |||
|
121 | Dependencies | |||
|
122 | ============ | |||
146 |
|
123 | |||
147 | Basic optional dependencies |
|
124 | IPython relies on a number of other Python packages. Installing using a package | |
148 | =========================== |
|
125 | manager like pip or conda will ensure the necessary packages are installed. If | |
|
126 | you install manually, it's up to you to make sure dependencies are installed. | |||
|
127 | They're not listed here, because they may change from release to release, so a | |||
|
128 | static list will inevitably get out of date. | |||
149 |
|
129 | |||
150 | There are a number of basic optional dependencies that most users will want to |
|
130 | It also has one key non-Python dependency which you may need to install separately. | |
151 | get. These are: |
|
|||
152 |
|
||||
153 | * readline (for command line editing, tab completion, etc.) |
|
|||
154 | * nose (to run the IPython test suite) |
|
|||
155 | * mock (Python < 3, also for tests) |
|
|||
156 |
|
||||
157 | If you are comfortable installing these things yourself, have at it, otherwise |
|
|||
158 | read on for more details. |
|
|||
159 |
|
||||
160 | IPython uses several other modules, such as pexpect_ and path.py, if they are |
|
|||
161 | installed on your system, but it can also use bundled versions from |
|
|||
162 | :mod:`IPython.external`, so there's no need to install them separately. |
|
|||
163 |
|
131 | |||
164 | readline |
|
132 | readline | |
165 | -------- |
|
133 | -------- | |
166 |
|
134 | |||
167 | As indicated above, on Windows, to get full functionality in the console |
|
135 | IPython's terminal interface relies on readline to provide features like tab | |
168 | version of IPython, PyReadline is needed. |
|
136 | completion and history navigation. If you only want to use IPython as a kernel | |
|
137 | for Jupyter notebooks and other frontends, you don't need readline. | |||
|
138 | ||||
|
139 | ||||
|
140 | **On Windows**, to get full console functionality, *PyReadline* is required. | |||
169 | PyReadline is a separate, Windows only implementation of readline that uses |
|
141 | PyReadline is a separate, Windows only implementation of readline that uses | |
170 | native Windows calls through :mod:`ctypes`. The easiest way of installing |
|
142 | native Windows calls through :mod:`ctypes`. The easiest way of installing | |
171 | PyReadline is you use the binary installer available `here |
|
143 | PyReadline is you use the binary installer available `here | |
172 | <http://pypi.python.org/pypi/pyreadline>`__. |
|
144 | <http://pypi.python.org/pypi/pyreadline>`__. | |
173 |
|
145 | |||
174 | On OS X, if you are using the built-in Python shipped by Apple, you will be |
|
146 | **On OS X**, if you are using the built-in Python shipped by Apple, you will be | |
175 | missing a proper readline implementation as Apple ships instead a library called |
|
147 | missing a proper readline implementation as Apple ships instead a library called | |
176 | ``libedit`` that provides only some of readline's functionality. While you may |
|
148 | ``libedit`` that provides only some of readline's functionality. While you may | |
177 | find libedit sufficient, we have occasional reports of bugs with it and several |
|
149 | find libedit sufficient, we have occasional reports of bugs with it and several | |
@@ -179,7 +151,8 b' developers who use OS X as their main environment consider libedit unacceptable' | |||||
179 | for productive, regular use with IPython. |
|
151 | for productive, regular use with IPython. | |
180 |
|
152 | |||
181 | Therefore, IPython on OS X depends on the :mod:`gnureadline` module. |
|
153 | Therefore, IPython on OS X depends on the :mod:`gnureadline` module. | |
182 |
We will *not* consider completion/history problems to be bugs for IPython if you |
|
154 | We will *not* consider completion/history problems to be bugs for IPython if you | |
|
155 | are using libedit. | |||
183 |
|
156 | |||
184 | To get a working :mod:`readline` module on OS X, do (with :mod:`pip` |
|
157 | To get a working :mod:`readline` module on OS X, do (with :mod:`pip` | |
185 | installed): |
|
158 | installed): | |
@@ -201,174 +174,7 b' optional dependencies:' | |||||
201 |
|
174 | |||
202 | $ pip install "ipython[terminal]" |
|
175 | $ pip install "ipython[terminal]" | |
203 |
|
176 | |||
|
177 | **On Linux**, readline is normally installed by default. If not, install it | |||
|
178 | from your system package manager. If you are compiling your own Python, make | |||
|
179 | sure you install the readline development headers first. | |||
204 |
|
180 | |||
205 | nose |
|
|||
206 | ---- |
|
|||
207 |
|
||||
208 | To run the IPython test suite you will need the :mod:`nose` package. Nose |
|
|||
209 | provides a great way of sniffing out and running all of the IPython tests. The |
|
|||
210 | simplest way of getting nose is to use :command:`pip`: |
|
|||
211 |
|
||||
212 | .. code-block:: bash |
|
|||
213 |
|
||||
214 | $ pip install nose |
|
|||
215 |
|
||||
216 | Another way of getting this is to do: |
|
|||
217 |
|
||||
218 | .. code-block:: bash |
|
|||
219 |
|
||||
220 | $ pip install "ipython[test]" |
|
|||
221 |
|
||||
222 | For more installation options, see the `nose website |
|
|||
223 | <https://nose.readthedocs.org>`_. |
|
|||
224 |
|
||||
225 | Once you have nose installed, you can run IPython's test suite using the |
|
|||
226 | iptest command: |
|
|||
227 |
|
||||
228 | .. code-block:: bash |
|
|||
229 |
|
||||
230 | $ iptest |
|
|||
231 |
|
||||
232 | Dependencies for IPython.parallel (parallel computing) |
|
|||
233 | ====================================================== |
|
|||
234 |
|
||||
235 | IPython's inter-process communication uses the PyZMQ_ bindings for the ZeroMQ_ messaging library. |
|
|||
236 | This is the only dependency for :mod:`IPython.parallel`. |
|
|||
237 |
|
||||
238 | Shortcut: |
|
|||
239 |
|
||||
240 | .. code-block:: bash |
|
|||
241 |
|
||||
242 | pip install "ipython[parallel]" |
|
|||
243 |
|
||||
244 | or manual |
|
|||
245 |
|
||||
246 | .. code-block:: bash |
|
|||
247 |
|
||||
248 | pip install pyzmq |
|
|||
249 |
|
||||
250 | PyZMQ provides wheels for current Python on OS X and Windows, so installing pyzmq will typically not require compilation. |
|
|||
251 |
|
||||
252 | IPython.parallel can use SSH tunnels, which require paramiko_ on Windows. |
|
|||
253 |
|
||||
254 | Dependencies for the IPython Qt console |
|
|||
255 | ======================================= |
|
|||
256 |
|
||||
257 | pyzmq_, pygments_, PyQt_ (or PySide_) |
|
|||
258 |
|
||||
259 | Shortcut: |
|
|||
260 |
|
||||
261 | .. code-block:: bash |
|
|||
262 |
|
||||
263 | pip install "ipython[qtconsole]" |
|
|||
264 |
|
||||
265 | or manual |
|
|||
266 |
|
||||
267 | .. code-block:: bash |
|
|||
268 |
|
||||
269 | pip install pyzmq pygments |
|
|||
270 |
|
||||
271 | PyQt/PySide are not pip installable, so generally must be installed via system package managers (or conda). |
|
|||
272 |
|
||||
273 | .. _installnotebook: |
|
|||
274 |
|
||||
275 | Dependencies for the IPython HTML notebook |
|
|||
276 | ========================================== |
|
|||
277 |
|
||||
278 | The HTML notebook is a complex web application with quite a few dependencies: |
|
|||
279 |
|
||||
280 | pyzmq_, jinja2_, tornado_, mistune_, jsonschema_, pygments_, terminado_ |
|
|||
281 |
|
||||
282 | Shortcut: |
|
|||
283 |
|
||||
284 | .. code-block:: bash |
|
|||
285 |
|
||||
286 | pip install "ipython[notebook]" |
|
|||
287 |
|
||||
288 | or manual: |
|
|||
289 |
|
||||
290 | .. code-block:: bash |
|
|||
291 |
|
||||
292 | pip install pyzmq jinja2 tornado mistune jsonschema pygments terminado |
|
|||
293 |
|
||||
294 | The IPython notebook is a notebook-style web interface to IPython and can be |
|
|||
295 | started with the command ``ipython notebook``. |
|
|||
296 |
|
||||
297 | MathJax |
|
|||
298 | ------- |
|
|||
299 |
|
||||
300 | The IPython notebook uses the MathJax_ Javascript library for rendering LaTeX |
|
|||
301 | in web browsers. Because MathJax is large, we don't include it with |
|
|||
302 | IPython. Normally IPython will load MathJax from a CDN, but if you have a slow |
|
|||
303 | network connection, or want to use LaTeX without an internet connection at all, |
|
|||
304 | you can install MathJax locally. |
|
|||
305 |
|
||||
306 | A quick and easy method is to install it from a python session:: |
|
|||
307 |
|
||||
308 | python -m IPython.external.mathjax |
|
|||
309 |
|
||||
310 | If you need tighter configuration control, you can download your own copy |
|
|||
311 | of MathJax from http://www.mathjax.org/download/ - use the MathJax-2.0 link. |
|
|||
312 | When you have the file stored locally, install it with:: |
|
|||
313 |
|
||||
314 | python -m IPython.external.mathjax /path/to/source/mathjax-MathJax-v2.0-20-g07669ac.zip |
|
|||
315 |
|
||||
316 | For unusual needs, IPython can tell you what directory it wants to find MathJax in:: |
|
|||
317 |
|
||||
318 | python -m IPython.external.mathjax -d /some/other/mathjax |
|
|||
319 |
|
||||
320 | By default MathJax will be installed in your ipython directory, but you |
|
|||
321 | can install MathJax system-wide. Please refer to the documentation |
|
|||
322 | of :mod:`IPython.external.mathjax` |
|
|||
323 |
|
||||
324 | Browser Compatibility |
|
|||
325 | --------------------- |
|
|||
326 |
|
||||
327 | The IPython notebook is officially supported on the following browsers: |
|
|||
328 |
|
||||
329 | * Chrome ≥ 13 |
|
|||
330 | * Safari ≥ 5 |
|
|||
331 | * Firefox ≥ 6 |
|
|||
332 |
|
||||
333 | The is mainly due to the notebook's usage of WebSockets and the flexible box model. |
|
|||
334 |
|
||||
335 | The following browsers are unsupported: |
|
|||
336 |
|
||||
337 | * Safari < 5 |
|
|||
338 | * Firefox < 6 |
|
|||
339 | * Chrome < 13 |
|
|||
340 | * Opera (any): CSS issues, but execution might work |
|
|||
341 | * Internet Explorer < 10 |
|
|||
342 | * Internet Explorer ≥ 10 (same as Opera) |
|
|||
343 |
|
||||
344 | Using Safari with HTTPS and an untrusted certificate is known to not work (websockets will fail). |
|
|||
345 |
|
||||
346 |
|
||||
347 | Dependencies for nbconvert (converting notebooks to various formats) |
|
|||
348 | ==================================================================== |
|
|||
349 |
|
||||
350 | For converting markdown to formats other than HTML, nbconvert uses Pandoc_ (1.12.1 or later). |
|
|||
351 |
|
||||
352 | To install pandoc on Linux, you can generally use your package manager:: |
|
|||
353 |
|
||||
354 | sudo apt-get install pandoc |
|
|||
355 |
|
||||
356 | On other platforms, you can get pandoc from `their website <http://johnmacfarlane.net/pandoc/installing.html>`_. |
|
|||
357 |
|
||||
358 |
|
||||
359 | .. _ZeroMQ: http://www.zeromq.org |
|
|||
360 | .. _PyZMQ: https://github.com/zeromq/pyzmq |
|
|||
361 | .. _paramiko: https://github.com/robey/paramiko |
|
|||
362 | .. _pygments: http://pygments.org |
|
|||
363 | .. _pexpect: http://pexpect.readthedocs.org/en/latest/ |
|
|||
364 | .. _Jinja: http://jinja.pocoo.org |
|
|||
365 | .. _Sphinx: http://sphinx-doc.org |
|
|||
366 | .. _pandoc: http://johnmacfarlane.net/pandoc |
|
|||
367 | .. _Tornado: http://www.tornadoweb.org |
|
|||
368 | .. _MathJax: http://www.mathjax.org |
|
|||
369 | .. _PyQt: http://www.riverbankcomputing.com/software/pyqt/intro |
|
|||
370 | .. _PySide: http://qt-project.org/wiki/PySide |
|
|||
371 | .. _jinja2: http://jinja.pocoo.org/ |
|
|||
372 | .. _mistune: https://github.com/lepture/mistune |
|
|||
373 | .. _jsonschema: https://github.com/Julian/jsonschema |
|
|||
374 | .. _terminado: https://github.com/takluyver/terminado |
|
General Comments 0
You need to be logged in to leave comments.
Login now