How to fix npm ERR! canvas@2.9.0 install: pkg-config: command not found in npm

npmINTERMEDIATEMEDIUMUpdated Dec 3, 2025· 106 views

This error occurs when installing node-canvas without the required system dependencies. Install Cairo and related graphics libraries for your Linux distribution to fix it.

Quick fix

Fixes npm ERR! canvas@2.9.0 install: pkg-config: command not found

sudo apt-get update
sudo apt-get install -y \
  build-essential \
  libcairo2-dev \
  libpango1.0-dev \
  libjpeg-dev \
  libgif-dev \
  librsvg2-dev \
  pkg-config
  1. Install dependencies on Ubuntu/Debian
  2. Install dependencies on CentOS/RHEL/Fedora
  3. Install dependencies on Alpine Linux
  4. Retry canvas installation
npm — error
sudo apt-get update
sudo apt-get install -y \
  build-essential \
  libcairo2-dev \
  libpango1.0-dev \
  libjpeg-dev \
  libgif-dev \
  librsvg2-dev \
  pkg-config
npm ERR! canvas@2.9.0 install: pkg-config: command not found

What this error means

The node-canvas package is a Cairo-backed Canvas implementation for Node.js. It requires several native graphics libraries to be installed on your system before npm can build it. pkg-config is a helper tool that helps the build process find installed libraries. When it's missing, the compilation can't locate the required dependencies. This error commonly occurs on minimal server installations, Docker containers, or CI environments that don't include development libraries by default.

Typical symptoms

  • npm install canvas fails with pkg-config not found
  • Errors mentioning cairo, pango, or libjpeg during canvas install
  • Installation works on development machines but fails on servers/CI
  • Docker builds fail when adding canvas dependency
  • node-gyp errors related to canvas compilation

Common causes

  1. pkg-config utility is not installed
  2. Cairo graphics library is missing
  3. Pango text rendering library is missing
  4. libjpeg, libpng, or giflib development headers missing
  5. Using minimal base image without development tools

How to fix "npm ERR! canvas@2.9.0 install: pkg-config: command not found"

1Install dependencies on Ubuntu/Debian

Install all required packages:

bash
sudo apt-get update
sudo apt-get install -y \
  build-essential \
  libcairo2-dev \
  libpango1.0-dev \
  libjpeg-dev \
  libgif-dev \
  librsvg2-dev \
  pkg-config
2Install dependencies on CentOS/RHEL/Fedora

For Red Hat-based systems:

bash
sudo yum install -y \
  gcc-c++ \
  cairo-devel \
  pango-devel \
  libjpeg-turbo-devel \
  giflib-devel \
  librsvg2-devel \
  pkgconfig

On Fedora, use dnf instead of yum.

3Install dependencies on Alpine Linux

For Alpine (common in Docker):

bash
apk add --no-cache \
  build-base \
  g++ \
  cairo-dev \
  pango-dev \
  jpeg-dev \
  giflib-dev \
  librsvg-dev \
  pkgconfig
4Retry canvas installation

After installing dependencies, install canvas:

bash
npm install canvas

Or rebuild if already in package.json:

bash
npm rebuild canvas

Advanced notes

For Docker, add dependencies in your Dockerfile:

dockerfile
FROM node:20

# Install canvas dependencies
RUN apt-get update && apt-get install -y \
  libcairo2-dev \
  libpango1.0-dev \
  libjpeg-dev \
  libgif-dev \
  librsvg2-dev \
  && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY package*.json ./
RUN npm ci

For multi-stage builds, remember that build dependencies are only needed in the build stage. The runtime stage needs the non-dev packages:

dockerfile
# Runtime stage only needs:
RUN apt-get update && apt-get install -y \
  libcairo2 libpango-1.0-0 libjpeg62-turbo libgif7 librsvg2-2

Consider using the canvas package's prebuilt binaries where available by checking their platform support documentation.

Frequently asked questions

What does "npm ERR! canvas@2.9.0 install: pkg-config: command not found" mean?
js. It requires several native graphics libraries to be installed on your system before npm can build it. pkg-config is a helper tool that helps the build process find installed libraries.
How do I fix "npm ERR! canvas@2.9.0 install: pkg-config: command not found"?
This error occurs when installing node-canvas without the required system dependencies. Install Cairo and related graphics libraries for your Linux distribution to fix it.
What causes "npm ERR! canvas@2.9.0 install: pkg-config: command not found"?
pkg-config utility is not installed Cairo graphics library is missing Pango text rendering library is missing
Is the "npm ERR! canvas@2.9.0 install: pkg-config: command not found" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading