🚀 Installing node-canvas on Mac M1 Without Tears

This guide helps you set up node-canvas on Mac M1 by addressing common dependency issues. Ensure you have Homebrew, Node.js, and necessary native libraries installed. Adjust your environment variables if needed, and then install node-canvas. Verify the installation to confirm it's working correctly.

Working with node-canvas on Mac M1 can be tricky because it depends on native libraries (like Cairo, Pango, and Pixman). If you’ve ever seen errors like:

package zlib was not found in the pkg-config search path
expat not found
freetype2 not found

…this guide will save you. ✅

---

🛠 Prerequisites

• macOS (M1 / M2 / Apple Silicon)

• Homebrew installed
  👉 Install it if missing:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  

• Node.js LTS (recommended: v18 or v20)
  👉 Use nvm:

    nvm install 18
    nvm use 18
  

---

📦 Install Required Dependencies

Run this one-liner to grab everything node-canvas needs:

brew install pkg-config cairo pango libpng jpeg giflib librsvg pixman zlib expat freetype libffi

This ensures all native libraries are available.

---

⚙️ Set Environment Variables (if needed)

Sometimes pkg-config can’t find the libs. Add this to your shell config (~/.zshrc or ~/.bashrc):

export PKG_CONFIG_PATH="$(brew --prefix)/lib/pkgconfig:$(brew --prefix)/opt/zlib/lib/pkgconfig:$(brew --prefix)/opt/libffi/lib/pkgconfig"

Then reload:

source ~/.zshrc

---

📥 Install node-canvas

Finally, install node-canvas:

npm install canvas

If you want to rebuild from source (safe option):

npm rebuild canvas --build-from-source

---

✅ Verify Installation

const { createCanvas } = require("canvas");
const canvas = createCanvas(200, 200);
console.log("Canvas working ✅", canvas.width, canvas.height);

Run:

node test.js

You should see:

Canvas working ✅ 200 200

---

🎉 Done!

Now node-canvas works smoothly on your Mac M1 without random errors.
If you hit more issues, double-check brew dependencies with:

brew list

Note: This steps are compiled using ChatGPT while solving such issue which I faced during my work.