Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

npm install canvas fails because cairo is not found

ErrorPackage cairo was not found in the pkg-config search path

Short answer

node-canvas ships prebuilt binaries for common systems. When none matches your platform or Node.js version, npm compiles it from source, and the build needs cairo and pango development packages that pkg-config can find. Use a supported platform and Node.js 22 or newer, or install the system libraries and retry.

  • Applies to canvas 3, Node.js 22, Ubuntu 24.04, macOS with Homebrew
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask pkg-config whether it can see cairo and pango, and print your Node.js version. The result decides which cause applies.

    node -v
    pkg-config --modversion cairo pango
  2. 2Match what you see, then jump to its fix

    1. 1The install log shows a compile step (node-gyp) and not a downloadNo prebuilt binary matches this platform or Node.js versionFix
    2. 2Package cairo was not found, and pkg-config --modversion cairo prints nothing on a Linux serverDebian or Ubuntu: the cairo and pango development packages are missingFix
    3. 3brew list shows cairo, yet the install still says it was not foundmacOS: the libraries are installed with Homebrew but pkg-config cannot see themFix

What does the error look like?

  • Package cairo was not found in the pkg-config search path
  • npm install canvas ends with a failed node-gyp build

Cause 1 of 3

No prebuilt binary matches this platform or Node.js version

1Check

The project README lists the platforms that get binaries (macOS x64 and arm64, Linux x64, x86 and arm64 on glibc or musl, Windows) and says the minimum Node.js version is 22. Anything outside that list compiles from source.

node -v
uname -m
ldd --version | head -n 1

2Fix

Move to a supported Node.js and architecture. Otherwise follow the next two causes and compile with system libraries.

nvm install 22
nvm use 22
npm install canvas

3Verify

The install finishes and the module loads.

node -e "require('canvas'); console.log('canvas ok')"

Confirmed by github.com

Did this fix it?

Cause 2 of 3

Debian or Ubuntu: the cairo and pango development packages are missing

1Check

The node-canvas wiki's Debian page lists the packages compilation needs.

dpkg -l | grep -E "libcairo2-dev|libpango1.0-dev"

2Fix

Install the packages the wiki names. The wiki marks libgif-dev, librsvg2-dev and libjpeg-dev optional (they add GIF, SVG and JPEG support).

sudo apt-get update
sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev
npm install canvas

3Verify

pkg-config now reports a version for cairo.

pkg-config --modversion cairo

Confirmed by github.com

Did this fix it?

Cause 3 of 3

macOS: the libraries are installed with Homebrew but pkg-config cannot see them

1Check

The wiki's macOS page installs the libraries with Homebrew and says a Homebrew cairo needs PKG_CONFIG_PATH set.

brew list | grep -E "cairo|pango|pkg-config"

2Fix

Install the packages from the wiki, and point PKG_CONFIG_PATH at the folder where your Homebrew keeps its .pc files. The wiki's example uses /usr/local; on Apple Silicon Homebrew lives elsewhere, so print the real path first.

brew install pkg-config cairo pango libpng jpeg giflib librsvg
export PKG_CONFIG_PATH="$(brew --prefix)/lib/pkgconfig:$PKG_CONFIG_PATH"
npm install canvas

3Verify

pkg-config finds cairo in the same shell.

pkg-config --modversion cairo

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Pin Node.js to a version the canvas README lists, and keep it in .nvmrc or engines.
  • In Docker, install the development packages in the build stage, and copy only the built node_modules.
  • Check the README's platform list before choosing a minimal or musl base image.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.