1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
.. highlight:: none
Installation
============
.. seealso::
`Installing Jupyter <https://jupyter.readthedocs.io/en/latest/install.html>`__
Nbconvert is part of the Jupyter ecosystem.
Supported Python versions
-------------------------
Currently Python 3.8-3.11 is supported and tested by nbconvert.
Installing nbconvert
--------------------
Nbconvert is packaged for both pip and conda, so you can install it with::
pip install nbconvert
# OR
conda install nbconvert
The `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_ and `Miniforge <https://github.com/conda-forge/miniforge/>`_ distributions both provide a minimal conda installation.
.. important::
To unlock its full capabilities, nbconvert requires Pandoc, TeX
(specifically, XeLaTeX) and playwright. These must be installed separately.
Installing Pandoc
-----------------
For converting markdown to formats other than HTML, nbconvert uses
`Pandoc <https://pandoc.org>`_ (1.12.1 or later).
To install pandoc on Linux, you can generally use your package manager::
sudo apt-get install pandoc
On other platforms, you can get pandoc from
`their website <https://pandoc.org/installing.html>`_.
Installing TeX
--------------
For converting notebooks to PDF (with ``--to pdf``), nbconvert makes use of LaTeX
and the XeTeX as the rendering engine.
.. versionadded:: 5.0
We use XeTeX as the rendering engine rather than pdfTeX (as
in earlier versions). XeTeX can access fonts through native
operating system libraries, it has better support for OpenType
formatted fonts and Unicode characters.
To install a complete TeX environment (including XeLaTeX and
the necessary supporting packages) by hand can be tricky.
Fortunately, there are packages that make this much easier. These
packages are specific to different operating systems:
* Linux: `TeX Live <http://tug.org/texlive/>`_
* E.g. on Debian or Ubuntu::
sudo apt-get install texlive-xetex texlive-fonts-recommended texlive-plain-generic
* macOS (OS X): `MacTeX <http://tug.org/mactex/>`_.
* Windows: `Latex Project <https://www.latex-project.org/get/>`_.
Because nbconvert depends on packages and fonts included in standard
TeX distributions, if you do not have a complete installation, you
may not be able to use nbconvert's standard tooling to convert
notebooks to PDF.
Installing Chromium
-------------------
For converting notebooks to PDF with ``--to webpdf``, nbconvert requires the
`playwright <https://github.com/microsoft/playwright-python>`_ Chromium automation library.
Playwright makes use of a specific version of Chromium. If it does not find a suitable
installation of the web browser, it can automatically download it if the ``--allow-chromium-download``
flag is passed to the command line.
To install a suitable version of playwright, you can pip install ``nbconvert[webpdf]``.
PDF conversion on a limited TeX environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you are only able to install a limited TeX environment, there are two main routes you could take to convert to PDF:
1. Using TeX by hand
a. You could convert to ``.tex`` directly; this requires Pandoc.
b. edit the file to accord with your local environment
c. run ``xelatex`` directly.
2. Custom exporter
a. You could write a :ref:`custom exporter <external_exporters>`
that takes your system's limitations into account.
|
