npm install canvas fails because cairo is not found
Package cairo was not found in the pkg-config search pathShort 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.
Fix it fast
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 pango2Match what you see, then jump to its fix
- 1
The install log shows a compile step (node-gyp) and not a downloadNo prebuilt binary matches this platform or Node.js versionFix - 2
Package 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
brew list shows cairo, yet the install still says it was not foundmacOS: the libraries are installed with Homebrew but pkg-config cannot see themFix
- 1
What does the error look like?
Package cairo was not found in the pkg-config search pathnpm 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 12Fix
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 canvas3Verify
The install finishes and the module loads.
node -e "require('canvas'); console.log('canvas ok')"Confirmed by github.com
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 canvas3Verify
pkg-config now reports a version for cairo.
pkg-config --modversion cairoConfirmed by github.com
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 canvas3Verify
pkg-config finds cairo in the same shell.
pkg-config --modversion cairoConfirmed by github.com
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
Back end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fixBack end
corepack enable fails: permission denied while creating the pnpm link
Internal Error: EACCES: permission denied, symlink '../lib/node_modules/corepack/dist/pnpm.js' -> '/usr/local/bin/pnpm'
corepack enable writes small link files for yarn and pnpm next to your node binary.
2 causes, each with a fixBack end
Create React App says Node is too old, and npm will not run on the new one
npm does not support Node.js v10.19.0
The shell is running an old Node.js that is below the version Create React App needs.
3 causes, each with a fixBack end
firebase deploy cannot load your functions: user code failed to load
Functions codebase could not be analyzed successfully. It may have a syntax or runtime error
The Firebase CLI loads your functions code on your machine before it deploys, to learn which functions exist.
4 causes, each with a fixBack end
firebase deploy stops because the predeploy lint step failed
Error: There was an error deploying functions
The predeploy hook in firebase.json runs npm run lint before every deploy, and a failing hook cancels the deploy.
3 causes, each with a fixBack end
fluent-ffmpeg cannot find the ffmpeg or ffprobe binary
Error: Cannot find ffprobe
fluent-ffmpeg does not bundle ffmpeg.
4 causes, each with a fix