git.iko.soy/typeable/pandoc
on 2.8 help sign in
typeable/pandoc/INSTALL.md
403 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], [gentoo] and [Void] 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 stack install pandoc-citeproc \
245 --flag "pandoc-citeproc:unicode_collation" \
246 --extra-lib-dirs=/usr/local/opt/icu4c/lib \
247 --extra-include-dirs=/usr/local/opt/icu4c/include
2496. The `pandoc.1` man page will be installed automatically. cabal shows
250 you where it is installed: you may need to set your `MANPATH`
251 accordingly. If `MANUAL.txt` has been modified, the man page can be
252 rebuilt: `make man/pandoc.1`.
254 The `pandoc-citeproc.1` man page will also be installed automatically.
257### Custom cabal method
259This is a step-by-step procedure that offers maximal control
260over the build and installation. Most users should use the
261quick install, but this information may be of use to packagers.
262For more details, see the [Cabal User's Guide]. These instructions
263assume that the pandoc source directory is your working directory.
264You will need cabal version 2.0 or higher.
2661. Install dependencies: in addition to the [Haskell platform],
267 you will need a number of additional libraries. You can install
268 them all with
270 cabal update
271 cabal install --only-dependencies
2732. Configure:
275 cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \
276 --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
277 --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
278 --mandir=DIR --flags=FLAGSPEC --enable-tests
280 All of the options have sensible defaults that can be overridden
281 as needed.
283 `FLAGSPEC` is a list of Cabal configuration flags, optionally
284 preceded by a `-` (to force the flag to `false`), and separated
285 by spaces. Pandoc's flags include:
287 - `embed_data_files`: embed all data files into the binary (default no).
288 This is helpful if you want to create a relocatable binary.
290 - `https`: enable support for downloading resources over https
291 (using the `http-client` and `http-client-tls` libraries).
2933. Build:
295 cabal build
296 cabal test
2984. Build API documentation:
300 cabal haddock --html-location=URL --hyperlink-source
3025. Copy the files:
304 cabal copy --destdir=PATH
306 The default destdir is `/`.
3086. Register pandoc as a GHC package:
310 cabal register
312 Package managers may want to use the `--gen-script` option to
313 generate a script that can be run to register the package at
314 install time.
316### Creating a relocatable binary
318It is possible to compile pandoc such that the data files
319pandoc uses are embedded in the binary. The resulting binary
320can be run from any directory and is completely self-contained.
321With cabal, add `-fembed_data_files` to the `cabal configure`
322or `cabal install` commands.
324With stack, use `--flag pandoc:embed_data_files`.
328### Running tests
330Pandoc comes with an automated test suite.
331To run with cabal, `cabal test`; to run with stack, `stack
332test`.
334To run particular tests (pattern-matching on their names), use
335the `-p` option:
337 cabal install pandoc --enable-tests
338 cabal test --test-options='-p markdown'
340Or with stack:
342 stack test --test-arguments='-p markdown'
344It is often helpful to add `-j4` (run tests in parallel)
345and `--hide-successes` (don't clutter output with successes)
346to the test arguments as well.
348If you add a new feature to pandoc, please add tests as well, following
349the pattern of the existing tests. The test suite code is in
350`test/test-pandoc.hs`. If you are adding a new reader or writer, it is
351probably easiest to add some data files to the `test` directory, and
352modify `test/Tests/Old.hs`. Otherwise, it is better to modify the module
353under the `test/Tests` hierarchy corresponding to the pandoc module you
354are changing.
356### Running benchmarks
358To build and run the benchmarks:
360 cabal configure --enable-benchmarks && cabal build
361 cabal bench
363or with stack:
365 stack bench
367To use a smaller sample size so the benchmarks run faster:
369 cabal bench --benchmark-options='-s 20'
371To run just the markdown benchmarks:
373 cabal bench --benchmark-options='markdown'
376[Arch]: https://www.archlinux.org/packages/community/x86_64/pandoc/
377[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
378[Debian]: https://packages.debian.org/pandoc
379[Fedora]: https://apps.fedoraproject.org/packages/pandoc
380[FreeBSD ports]: http://www.freshports.org/textproc/pandoc/
381[GHC]: http://www.haskell.org/ghc/
382[GPL]: http://www.gnu.org/copyleft/gpl.html
383[Haskell platform]: http://hackage.haskell.org/platform/
384[MacPorts]: http://trac.macports.org/browser/trunk/dports/textproc/pandoc/Portfile
385[MacTeX]: https://tug.org/mactex/
386[BasicTeX]: http://www.tug.org/mactex/morepackages.html
387[LaTeX]: https://www.latex-project.org
388[MiKTeX]: http://miktex.org/
389[librsvg]: https://wiki.gnome.org/Projects/LibRsvg
390[Python]: https://www.python.org
391[NetBSD]: http://pkgsrc.se/wip/pandoc
392[NixOS]: https://nixos.org/nixos/packages.html
393[Slackware]: https://www.slackbuilds.org/result/?search=pandoc&sv=
394[Ubuntu]: https://packages.ubuntu.com/pandoc
395[download page]: https://github.com/jgm/pandoc/releases/latest
396[gentoo]: http://packages.gentoo.org/package/app-text/pandoc
397[haskell repository]: https://wiki.archlinux.org/index.php/Haskell_Package_Guidelines#.5Bhaskell.5D
398[openSUSE]: https://software.opensuse.org/package/pandoc
399[source tarball]: http://hackage.haskell.org/package/pandoc
400[stack]: https://docs.haskellstack.org/en/stable/install_and_upgrade.html
401[cabal-install]: http://hackage.haskell.org/package/cabal-install
402[Void]: https://voidlinux.org/
403[uninstaller]: https://raw.githubusercontent.com/jgm/pandoc/master/macos/uninstall-pandoc.pl