lecture.studio

Install Marp: CLI, VS Code and Docker on Mac, Windows, Linux

By Ekrem Çetinkaya · Published

There are three ways to run Marp and they do not conflict: npx @marp-team/marp-cli@latest deck.md runs the converter without installing anything, npm install -g @marp-team/marp-cli puts a marp command on the PATH, and the VS Code extension previews and exports from the editor. The CLI needs Node 18 or newer, and PDF, PPTX and image export additionally need a Chrome-family browser on the machine.

This guide covers each route, the Docker image, what the browser is for, and the two install problems that come up most.

Run it without installing

npx @marp-team/marp-cli@latest deck.md -o deck.html
npx @marp-team/marp-cli@latest deck.md --pdf

npx downloads the package into its cache and runs it. Pinning @latest — or a version, @4.5.1 — keeps a cached older copy from being reused. This is the route to prefer on a shared machine, in a script you hand to a colleague, and anywhere you do not want a global install to drift.

One detail that costs people ten minutes: run marp-cli from a script or an editor task with stdin closed (marp deck.md --pdf < /dev/null). With an open pipe and no file argument it waits for Markdown on stdin and looks like it has hung.

Install the command

npm install -g @marp-team/marp-cli
marp --version
# @marp-team/marp-cli v4.5.1 (w/ @marp-team/marp-core v4.4.0)

macOS also has brew install marp-cli, which is the same package wrapped by Homebrew. Whichever you use, remember it is a Node program: it is tied to the Node that installed it.

The Node upgrade trap. On this machine a global marp-cli 4.2.0, installed under an older Node, stopped working after Node was upgraded to 26:

ReferenceError: require is not defined in ES module scope, you can use import instead
    at .../node_modules/yargs/yargs:3:69

Nothing is wrong with Marp — the old dependency tree is no longer loadable by the new Node. Reinstall (npm install -g @marp-team/marp-cli) and the current release runs fine. If the machine gets Node upgrades you do not control, the npx form avoids the whole class of problem.

VS Code

Install Marp for VS Code from the marketplace, then add marp: true to the front matter of a Markdown file and open the preview. The extension bundles its own copy of Marp Core, so it does not need the CLI, and it exports PDF, PPTX, HTML and images from the command palette. Its settings cover HTML handling, the math engine, and whether PDF export carries the notes. Details and the settings list are in Marp in VS Code.

Use both together on a course: the extension while writing, the CLI in a script or GitHub Action to export every deck in the folder.

Docker

The Marp team publishes an image, marpteam/marp-cli, which packages the CLI with a browser so a build machine does not need Node or Chrome installed. The documented invocation mounts the working directory:

docker run --rm --init -v $PWD:/home/marp/app/ -e LANG=$LANG marpteam/marp-cli deck.md --pdf

This is from the project's documentation, not something tested here — the Docker daemon was not running on the machine used for this post. It is the route that CI systems use; the Actions guide shows the workflow variant.

What the browser is for

HTML export is pure Node. PDF, PPTX and PNG/JPEG export drive a headless Chrome, Edge or Firefox to render the slides. If none is installed, export fails; the flags and environment variables that control it:

marp deck.md --pdf --browser chrome          # auto | chrome | edge | firefox
marp deck.md --pdf --browser-path /path/to/chrome
CHROME_PATH=/path/to/chrome marp deck.md --pdf

marp-cli also honours CHROME_NO_SANDBOX (containers and some CI runners), CHROME_DISABLE_GPU, and FIREFOX_PATH. On a server with no browser at all, install Chromium from the distribution's packages or use the Docker image above.

Which one should a course use?

The files are Markdown either way, so switching later costs nothing. Nothing needs installing at all to try the syntax: the online editor runs Marp in the browser, and Lecture Studio writes the same Markdown from your sources on a Mac (free during the beta, needs an Oberik project key).

FAQ

How do I install Marp CLI on Windows?

npm install -g @marp-team/marp-cli in PowerShell, after installing Node 18 or newer. Export to PDF also needs Chrome or Edge, which Windows normally has.

How do I install Marp on macOS?

npm install -g @marp-team/marp-cli or brew install marp-cli. Both need Node; reinstall after a Node major upgrade.

Do I need Node to use Marp?

For the CLI, yes — Node 18 or newer. The VS Code extension and the online editor do not need it.

Does Marp need Chrome?

Only for PDF, PPTX and image export. HTML export works without a browser. Point marp-cli at a specific binary with --browser-path or CHROME_PATH.

More guides