Get started

Install

Two commands on most machines, and one more only if you want PDFs.

Amethyst is a Python package with a single system dependency, and only the PDF path needs it. Word output needs nothing but Python. Either way there is no stylesheet to write and no reference .docx to keep in sync — the install is the whole setup.

  1. Check your Python

    Amethyst needs Python 3.10 or newer. It is tested on 3.10, 3.11, 3.12 and 3.13.

    $ python3 --versionPython 3.12.7

    If that prints something older, or nothing at all, install a current Python first. Amethyst has no opinion about how you do it.

  2. Install the CLI

    uv puts the tool in an environment of its own and on your PATH in one step, which is what you want for something you run rather than import.

    $ uv tool install amethyst-cli

    Or into an environment you manage yourself:

    $ pip install amethyst-cli

    The package is amethyst-cli and the command it installs is amethyst. Only the name you install differs.

  3. Install Pango, if you want PDFs

    PDF output is laid out by WeasyPrint, which loads Pango — a text-shaping library — through cffi at render time. It cannot be installed from PyPI, so it is the one thing here you install outside Python.

    macOS
    brew install pango
    Debian, Ubuntu
    sudo apt install libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0
    Fedora
    sudo dnf install pango

    DOCX output needs none of it. On a machine with no Pango, amethyst --help and -f docx work normally, and only -f pdf fails — with one line naming what to install, and exit code 3. If Word is all you need, skip this step and come back when it isn’t.

    Nothing else is required. Install guides for WeasyPrint often mention libffi as well; that is a holdover from when pip compiled cffi from source, and the cffi wheel is prebuilt now.

  4. Check it worked

    $ amethyst --version

    A version number means the command is on your PATH. To see that it can load its own themes as well:

    $ amethyst themes listacademic  A quiet book serif, a narrow measure and generous margins.default   A serif text face, roomy leading and a violet accent.github    GitHub's Markdown look: system sans, blue links, quiet rules.

  5. Convert something

    Point it at a Markdown file. The format comes from -f, or from an -o path ending .pdf or .docx — Amethyst does not default to PDF, and saying neither is a usage error rather than a guess.

    $ amethyst convert notes.md -o notes.pdf$ amethyst convert notes.md -f docx

    That is the whole tool with nothing configured. Everything else is a flag on top of it — a contents, a cover, a different theme — and amethyst init writes you a config file to keep them in, so you stop typing them.

    $ amethyst convert report.md -o report.pdf --toc --title-page -t academic

If it didn’t work

The three failures that happen at install time, and what each one means.

error: PDF output needs Pango, which is not installed.exit 3

Step three did not happen, or did not take. Run your platform’s command above — or convert to Word instead, which needs nothing.

error: Pango is installed in …, but WeasyPrint could not load it from there.exit 3

Pango is present and Amethyst has already pointed the loader at it, so the usual cause is an architecture mismatch — Homebrew’s libraries built for one of arm64 or x86_64 and your Python for the other. Check that brew config and python -c "import platform; print(platform.machine())" agree.

You do not need to export DYLD_FALLBACK_LIBRARY_PATH. Amethyst puts Homebrew’s lib directory on the loader path itself, in-process, and exporting it in a shell would not work anyway — macOS strips every DYLD_* variable when it executes a system-protected binary.

error: No output format given.exit 2

Amethyst does not default to PDF. Pass -f pdf, name the output -o out.pdf, or set format = "pdf" in a config file.

Everything past this point — every flag, the five places a setting can come from, the theme file both renderers read — is in the reference.

Read the documentationSource on GitHub