Fix installing the Node.js canvas package on macOS

I wanted to use the Node.js canvas NPM package but running npm install canvas failed with messages like this:

npm ERR! code 1
npm ERR! path /Users/flaviocopes/dev/old/generate-images-posts/node_modules/canvas
npm ERR! command failed
npm ERR! command sh -c node-pre-gyp install --fallback-to-build
npm ERR! Failed to execute '/opt/homebrew/Cellar/node@16/16.14.2/bin/node /opt/homebrew/Cellar/node@16/16.14.2/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js configure --fallback-to-build --module=/Users/flaviocopes/dev/old/generate-images-posts/node_modules/canvas/build/Release/canvas.node --module_name=canvas --module_path=/Users/flaviocopes/dev/old/generate-images-posts/node_modules/canvas/build/Release --napi_version=8 --node_abi_napi=napi --napi_build_version=0 --node_napi_label=node-v93' (1)
npm ERR! node-pre-gyp info it worked if it ends with ok
npm ERR! node-pre-gyp info using node-pre-gyp@0.11.0
npm ERR! node-pre-gyp info using node@16.14.2 | darwin | arm64
npm ERR! node-pre-gyp WARN Using request for node-pre-gyp https download 
npm ERR! node-pre-gyp info check checked for "/Users/flaviocopes/dev/old/generate-images-posts/node_modules/canvas/build/Release/canvas.node" (not found)
npm ERR! node-pre-gyp http GET https://github.com/node-gfx/node-canvas-prebuilt/releases/download/v2.6.1/canvas-v2.6.1-node-v93-darwin-unknown-arm64.tar.gz
npm ERR! node-pre-gyp http 404 https://github.com/node-gfx/node-canvas-prebuilt/releases/download/v2.6.1/canvas-v2.6.1-node-v93-darwin-unknown-arm64.tar.gz
npm ERR! node-pre-gyp WARN Tried to download(404): https://github.com/node-gfx/node-canvas-prebuilt/releases/download/v2.6.1/canvas-v2.6.1-node-v93-darwin-unknown-arm64.tar.gz 
npm ERR! node-pre-gyp WARN Pre-built binaries not found for canvas@2.6.1 and node@16.14.2 (node-v93 ABI, unknown) (falling back to source compile with node-gyp) 
npm ERR! node-pre-gyp http 404 status code downloading tarball https://github.com/node-gfx/node-canvas-prebuilt/releases/download/v2.6.1/canvas-v2.6.1-node-v93-darwin-unknown-arm64.tar.gz 
npm ERR! gyp info it worked if it ends with ok
npm ERR! gyp info using node-gyp@8.4.1
npm ERR! gyp info using node@16.14.2 | darwin | arm64

To fix this, I ran:

brew install pkg-config cairo pango libpng jpeg giflib librsvg 

and npm install canvas worked fine!

Why this happens

canvas isn’t pure JavaScript. It’s a native module that draws images using Cairo, a C graphics library. So installing it means compiling C code that links against Cairo and a few related libraries.

To save you that compile step, the package first tries to download a prebuilt binary. That’s the node-pre-gyp http GET line in the log. When no prebuilt binary matches your exact combination of Node version, platform, and CPU, that download 404s. On Apple Silicon Macs the darwin-arm64 build often isn’t published, which is exactly the 404 you see above.

At that point node-pre-gyp falls back to building from source with node-gyp. And that only works if the C libraries it needs are already on your machine. They aren’t by default, so the build fails.

The brew install line installs those libraries: Cairo and Pango for drawing and text, libpng, jpeg, and giflib for image formats, librsvg for SVG, and pkg-config so the build can find them all.

A variation of the same error

If Cairo is missing when the build starts, you’ll see a clearer message instead:

Package cairo was not found in the pkg-config search path.

Same root cause, same fix. Run the brew install command, then run npm install again. Homebrew puts these libraries where pkg-config looks, the source compile finishes, and the install succeeds.