git.iko.soy/typeable/pandoc
on 2.6 help sign in
typeable/pandoc/INSTALL.md
401 lines 14 kB history raw
1# Installing pandoc
3The simplest way to get the latest pandoc release is to use the installer.
5<a href="https://github.com/jgm/pandoc/releases/latest"
6 class="btn btn-primary" id="downloadInstallerBtn">
7 Download the latest installer
8</a>
10For alternative ways to install pandoc, see below
11under the heading for your operating system.
13## Windows
15 - There is a package installer at pandoc's [download page].
16 This will install pandoc, replacing older versions, and
17 update your path to include the directory where pandoc's
18 binaries are installed.
20 - If you prefer not to use the msi installer, we also provide
21 a zip file that contains pandoc's binaries and
22 documentation. Simply unzip this file and move the binaries
23 to a directory of your choice.
25 - Alternatively, you can install pandoc using
26 [Chocolatey](https://chocolatey.org):
28 choco install pandoc
30 Chocolatey can also install other software that integrates with Pandoc.
31 For example, to install `rsvg-convert` (from [librsvg], covering formats
32 without SVG support), [Python] (to use Pandoc filters), and
33 [MiKTeX] (to typeset PDFs with [LaTeX]):
35 choco install rsvg-convert python miktex
37 - By default, Pandoc creates PDFs using LaTeX.
38 We recommend installing it via [MiKTeX].
40## macOS
42 - There is a package installer at pandoc's [download page].
43 If you later want to uninstall the package, you can do so
44 by downloading [this script][uninstaller]
45 and running it with `perl uninstall-pandoc.pl`.
47 - Alternatively, you can install pandoc using
48 [Homebrew](http://brew.sh):
50 brew install pandoc
52 To include pandoc's citation parser:
54 brew install pandoc-citeproc
56 Homebrew can also install other software that integrates with Pandoc.
57 For example, to install [librsvg] (its `rsvg-convert` covers formats
58 without SVG support), [Python] (to use Pandoc filters), and
59 [BasicTeX] (to typeset PDFs with [LaTeX]):
61 brew install librsvg python homebrew/cask/basictex
63 Note: On unsupported versions of macOS (more than three releases old),
64 Homebrew installs from source, which takes additional time and disk space
65 for the `ghc` compiler and dependent Haskell libraries.
67 - We also provide a zip file containing the binaries and man
68 pages, for those who prefer not to use the installer. Simply
69 unzip the file and move the binaries and man pages to
70 whatever directory you like.
72 - By default, Pandoc creates PDFs using LaTeX. Because a full [MacTeX]
73 installation uses four gigabytes of disk space, we recommend
74 [BasicTeX] or [TinyTeX](https://yihui.name/tinytex/)
75 and using the `tlmgr` tool to install additional packages
76 as needed. If you receive errors warning of fonts not found:
78 tlmgr install collection-fontsrecommended
80## Linux
82 - Check whether the pandoc version in your package manager is
83 not outdated. Pandoc is in the [Debian], [Ubuntu], [Slackware],
84 [Arch], [Fedora], [NiXOS], [openSUSE], and [gentoo] repositories.
86 - To get the latest release, we provide a binary package for amd64
87 architecture on the **[download page]**.
89 This provides both `pandoc` and `pandoc-citeproc`.
90 The executables are statically linked and
91 have no dynamic dependencies or dependencies on external
92 data files. Note: because of the static
93 linking, the pandoc binary from this package cannot use lua
94 filters that require external lua modules written in C.
96 Both a tarball and a deb installer are provided. To install the deb:
98 sudo dpkg -i $DEB
100 where `$DEB` is the path to the downloaded deb. This will
101 install the `pandoc` and `pandoc-citeproc` executables and
102 man pages.
104 If you use an RPM-based distro, you may be able to install
105 the deb from our download page using `alien`.
107 On any distro, you may install from the tarball into `$DEST`
108 (say, `/usr/local/` or `$HOME/.local`) by doing
110 tar xvzf $TGZ --strip-components 1 -C $DEST
112 where `$TGZ` is the path to the downloaded zipped tarball.
113 For Pandoc versions before 2.0, which don't provide
114 a tarball, try instead
116 ar p $DEB data.tar.gz | tar xvz --strip-components 2 -C $DEST
118 - You can also install from source, using the
119 instructions below under [Compiling from source].
120 Note that most distros have the Haskell platform in their
121 package repositories. For example, on Debian/Ubuntu,
122 you can install it with `apt-get install haskell-platform`.
124 - For PDF output, you'll need LaTeX. We recommend installing
125 [TeX Live](http://www.tug.org/texlive/) via your package
126 manager. (On Debian/Ubuntu, `apt-get install texlive`.)
128## Chrome OS
130On Chrome OS, pandoc can be installed using the
131[chromebrew](https://github.com/skycocker/chromebrew) package manager
132with the command:
134```sh
135crew install pandoc
136```
138This will automatically build and configure pandoc for the specific
139device you are using.
141## BSD
143 - Pandoc is in the [NetBSD] and [FreeBSD ports] repositories.
145## Compiling from source
147If for some reason a binary package is not available for your
148platform, or if you want to hack on pandoc or use a non-released
149version, you can install from source.
151### Getting the pandoc source code
153Source tarballs can be found at
154<https://hackage.haskell.org/package/pandoc>. For example, to
155fetch the source for version 1.17.0.3:
157 wget https://hackage.haskell.org/package/pandoc-1.17.0.3/pandoc-1.17.0.3.tar.gz
158 tar xvzf pandoc-1.17.0.3.tar.gz
159 cd pandoc-1.17.0.3
161Or you can fetch the development code by cloning the repository:
163 git clone https://github.com/jgm/pandoc
164 cd pandoc
166Note: there may be times when the development code is broken
167or depends on other libraries which must be installed
168separately. Unless you really know what you're doing, install
169the last released version.
171### Quick stack method
173The easiest way to build pandoc from source is to use [stack][stack]:
1751. Install [stack][stack]. Note that Pandoc requires stack >= 1.7.0.
1772. Change to the pandoc source directory and issue the following commands:
179 stack setup
180 stack install
182 `stack setup` will automatically download the ghc compiler
183 if you don't have it. `stack install` will install the
184 `pandoc` executable into `~/.local/bin`, which you should
185 add to your `PATH`. This process will take a while, and
186 will consume a considerable amount of disk space.
188### Quick cabal method
1901. Install the [Haskell platform]. This will give you [GHC] and
191 the [cabal-install] build tool. Note that pandoc requires
192 GHC >= 7.10 and cabal >= 2.0.
1942. Update your package database:
196 cabal update
1983. Check your cabal version with
200 cabal --version
202 If you have a version less than 2.0, install the latest with:
204 cabal install cabal-install
2064. Use `cabal` to install pandoc and its dependencies:
208 cabal install pandoc
210 This procedure will install the released version of pandoc,
211 which will be downloaded automatically from HackageDB.
213 If you want to install a modified or development version
214 of pandoc instead, switch to the source directory and do
215 as above, but without the 'pandoc':
217 cabal install
2195. Make sure the `$CABALDIR/bin` directory is in your path. You should
220 now be able to run `pandoc`:
222 pandoc --help
224 [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file)
2265. If you want to process citations with pandoc, you will also need to
227 install a separate package, `pandoc-citeproc`. This can be installed
228 using cabal:
230 cabal install pandoc-citeproc
232 By default `pandoc-citeproc` uses the "i;unicode-casemap" method
233 to sort bibliography entries (RFC 5051). If you would like to
234 use the locale-sensitive unicode collation algorithm instead,
235 specify the `unicode_collation` flag:
237 cabal install pandoc-citeproc -funicode_collation
239 Note that this requires the `text-icu` library, which in turn
240 depends on the C library `icu4c`. Installation directions
241 vary by platform. Here is how it might work on macOS with Homebrew:
243 brew install icu4c
244 cabal install --extra-lib-dirs=/usr/local/Cellar/icu4c/51.1/lib \
245 --extra-include-dirs=/usr/local/Cellar/icu4c/51.1/include \
246 -funicode_collation text-icu pandoc-citeproc
2486. The `pandoc.1` man page will be installed automatically. cabal shows
249 you where it is installed: you may need to set your `MANPATH`
250 accordingly. If `MANUAL.txt` has been modified, the man page can be
251 rebuilt: `make man/pandoc.1`.
253 The `pandoc-citeproc.1` man page will also be installed automatically.
256### Custom cabal method
258This is a step-by-step procedure that offers maximal control
259over the build and installation. Most users should use the
260quick install, but this information may be of use to packagers.
261For more details, see the [Cabal User's Guide]. These instructions
262assume that the pandoc source directory is your working directory.
263You will need cabal version 2.0 or higher.
2651. Install dependencies: in addition to the [Haskell platform],
266 you will need a number of additional libraries. You can install
267 them all with
269 cabal update
270 cabal install --only-dependencies
2722. Configure:
274 cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \
275 --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
276 --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
277 --mandir=DIR --flags=FLAGSPEC --enable-tests
279 All of the options have sensible defaults that can be overridden
280 as needed.
282 `FLAGSPEC` is a list of Cabal configuration flags, optionally
283 preceded by a `-` (to force the flag to `false`), and separated
284 by spaces. Pandoc's flags include:
286 - `embed_data_files`: embed all data files into the binary (default no).
287 This is helpful if you want to create a relocatable binary.
289 - `https`: enable support for downloading resources over https
290 (using the `http-client` and `http-client-tls` libraries).
2923. Build:
294 cabal build
295 cabal test
2974. Build API documentation:
299 cabal haddock --html-location=URL --hyperlink-source
3015. Copy the files:
303 cabal copy --destdir=PATH
305 The default destdir is `/`.
3076. Register pandoc as a GHC package:
309 cabal register
311 Package managers may want to use the `--gen-script` option to
312 generate a script that can be run to register the package at
313 install time.
315### Creating a relocatable binary
317It is possible to compile pandoc such that the data files
318pandoc uses are embedded in the binary. The resulting binary
319can be run from any directory and is completely self-contained.
320With cabal, add `-fembed_data_files` to the `cabal configure`
321or `cabal install` commands.
323With stack, use `--flag pandoc:embed_data_files`.
327### Running tests
329Pandoc comes with an automated test suite.
330To run with cabal, `cabal test`; to run with stack, `stack
331test`.
333To run particular tests (pattern-matching on their names), use
334the `-p` option:
336 cabal install pandoc --enable-tests
337 cabal test --test-options='-p markdown'
339Or with stack:
341 stack test --test-arguments='-p markdown'
343It is often helpful to add `-j4` (run tests in parallel)
344and `--hide-successes` (don't clutter output with successes)
345to the test arguments as well.
347If you add a new feature to pandoc, please add tests as well, following
348the pattern of the existing tests. The test suite code is in
349`test/test-pandoc.hs`. If you are adding a new reader or writer, it is
350probably easiest to add some data files to the `test` directory, and
351modify `test/Tests/Old.hs`. Otherwise, it is better to modify the module
352under the `test/Tests` hierarchy corresponding to the pandoc module you
353are changing.
355### Running benchmarks
357To build and run the benchmarks:
359 cabal configure --enable-benchmarks && cabal build
360 cabal bench
362or with stack:
364 stack bench
366To use a smaller sample size so the benchmarks run faster:
368 cabal bench --benchmark-options='-s 20'
370To run just the markdown benchmarks:
372 cabal bench --benchmark-options='markdown'
375[Arch]: https://www.archlinux.org/packages/community/x86_64/pandoc/
376[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
377[Debian]: https://packages.debian.org/pandoc
378[Fedora]: https://apps.fedoraproject.org/packages/pandoc
379[FreeBSD ports]: http://www.freshports.org/textproc/pandoc/
380[GHC]: http://www.haskell.org/ghc/
381[GPL]: http://www.gnu.org/copyleft/gpl.html
382[Haskell platform]: http://hackage.haskell.org/platform/
383[MacPorts]: http://trac.macports.org/browser/trunk/dports/textproc/pandoc/Portfile
384[MacTeX]: https://tug.org/mactex/
385[BasicTeX]: http://www.tug.org/mactex/morepackages.html
386[LaTeX]: https://www.latex-project.org
387[MiKTeX]: http://miktex.org/
388[librsvg]: https://wiki.gnome.org/Projects/LibRsvg
389[Python]: https://www.python.org
390[NetBSD]: http://pkgsrc.se/wip/pandoc
391[NixOS]: https://nixos.org/nixos/packages.html
392[Slackware]: https://www.slackbuilds.org/result/?search=pandoc&sv=
393[Ubuntu]: https://packages.ubuntu.com/pandoc
394[download page]: https://github.com/jgm/pandoc/releases/latest
395[gentoo]: http://packages.gentoo.org/package/app-text/pandoc
396[haskell repository]: https://wiki.archlinux.org/index.php/Haskell_Package_Guidelines#.5Bhaskell.5D
397[openSUSE]: https://software.opensuse.org/package/pandoc
398[source tarball]: http://hackage.haskell.org/package/pandoc
399[stack]: https://docs.haskellstack.org/en/stable/install_and_upgrade.html
400[cabal-install]: http://hackage.haskell.org/package/cabal-install
401[uninstaller]: https://raw.githubusercontent.com/jgm/pandoc/master/macos/uninstall-pandoc.pl