How to fix npm ERR! code ENOTSUP npm ERR! notsup Unsupported libc: {"libc":"glibc"} (current: {"libc":"musl"}) in npm

npmINTERMEDIATEHIGHUpdated Dec 6, 2025· 232 views

The ENOTSUP libc error occurs when npm packages with native binaries are built for glibc but your system uses musl (or vice versa). This commonly happens with Alpine Linux Docker images. Switch to a glibc-based image or rebuild packages from source.

Quick fix

Fixes ENOTSUP

# Instead of this (Alpine/musl):
FROM node:20-alpine

# Use this (Debian/glibc):
FROM node:20
# or
FROM node:20-slim
  1. Switch to a glibc-based Docker image
  2. Add glibc compatibility layer to Alpine
  3. Build native modules from source
  4. Use npm flags to specify target platform
npm — error
# Instead of this (Alpine/musl):
FROM node:20-alpine
# Use this (Debian/glibc):
FROM node:20
# or
FROM node:20-slim
npm ERR! code ENOTSUP
npm ERR! notsup Unsupported libc: {"libc":"glibc"} (current: {"libc":"musl"})

What this error means

This error occurs when npm tries to install a package with prebuilt native binaries that were compiled for a different C library than your system uses. Linux systems use one of two main C libraries: glibc (GNU C Library, used by Debian, Ubuntu, CentOS) or musl (used by Alpine Linux). When a package like Sharp, bcrypt, or esbuild publishes prebuilt binaries, they're compiled against a specific libc. If you're running Alpine Linux (musl) but the package only has glibc binaries available, npm cannot install the prebuilt version and reports this ENOTSUP error. This is particularly common in Docker environments where Alpine images are popular for their small size, but many npm packages don't provide musl-compatible prebuilds.

Typical symptoms

  • npm install fails with 'Unsupported libc' or 'notsup' error
  • Error mentions glibc vs musl mismatch
  • Package installs locally but fails in Docker Alpine containers
  • CI/CD pipeline fails while local development works
  • Error occurs with packages like sharp, bcrypt, esbuild, or other native modules
  • Build succeeds but application crashes at runtime with missing library errors
  • Error message includes platform details like {"os":"linux","libc":"musl"}

Common causes

  1. Using Alpine Linux Docker image (musl-based) with packages built for glibc
  2. Package doesn't provide prebuilt binaries for musl libc
  3. Copying node_modules from a glibc system to a musl system
  4. AWS Lambda or serverless environment using different libc than development machine
  5. Older glibc version on system (e.g., Amazon Linux 2 with glibc 2.26) incompatible with newer packages
  6. Cross-compilation targeting wrong libc variant

How to fix "npm ERR! code ENOTSUP npm ERR! notsup Unsupported libc: {"libc":"glibc"} (current: {"libc":"musl"})"

1Switch to a glibc-based Docker image

The simplest fix is to use a Debian or Ubuntu-based Node.js image instead of Alpine:

dockerfile
# Instead of this (Alpine/musl):
FROM node:20-alpine

# Use this (Debian/glibc):
FROM node:20
# or
FROM node:20-slim

The official node:20 and node:20-slim images use Debian with glibc, which is compatible with most npm packages.

2Add glibc compatibility layer to Alpine

If you must use Alpine, install the glibc compatibility package:

dockerfile
FROM node:20-alpine

RUN apk add --no-cache libc6-compat

This provides a compatibility layer that allows some glibc-built binaries to run on musl systems. Note: this doesn't work for all packages.

3Build native modules from source

Force npm to compile native modules on your system instead of using prebuilds:

dockerfile
FROM node:20-alpine

# Install build dependencies
RUN apk add --no-cache python3 make g++

# Force rebuild from source
RUN npm install --build-from-source

This compiles the native code against your system's libc, ensuring compatibility.

4Use npm flags to specify target platform

Explicitly tell npm which platform to target:

bash
npm install --cpu=x64 --os=linux --libc=glibc

This is useful in CI systems where the build environment differs from the deployment target.

5Delete node_modules and reinstall in target environment

If you copied node_modules between systems, delete and reinstall:

bash
rm -rf node_modules package-lock.json
npm install

Native modules must be installed on the target system, not copied from another environment.

6Check package documentation for Alpine support

Some packages provide specific Alpine installation instructions. For example, Sharp recommends:

dockerfile
FROM node:20-alpine
RUN apk add --no-cache vips-dev

Check the package's GitHub repository or npm page for platform-specific guidance.

Advanced notes

The glibc vs musl incompatibility is a fundamental architectural difference, not just a missing dependency. musl is designed for simplicity and small size (making Alpine images ~5MB vs ~100MB for Debian), but this comes at the cost of binary compatibility.

For AWS Lambda, the runtime uses Amazon Linux (glibc). If you build your deployment package on Alpine, native modules will fail at runtime. Always build Lambda packages on a glibc-based system or use the official AWS SAM build containers.

Some packages like esbuild handle this gracefully by publishing separate npm packages for each platform (@esbuild/linux-x64, @esbuild/linux-arm64, etc.). If you see errors about missing @package/linux-x64-musl, the package may not support your platform at all.

For production deployments, consider whether Alpine's smaller image size is worth the complexity. A 100MB Debian image that works reliably is often better than a 5MB Alpine image that requires extensive workarounds.

Frequently asked questions

What does "ENOTSUP" mean?
This error occurs when npm tries to install a package with prebuilt native binaries that were compiled for a different C library than your system uses. Linux systems use one of two main C libraries: glibc (GNU C Library, used by Debian, Ubuntu, CentOS) or musl (used by Alpine Linux). When a package like Sharp, bcrypt, or esbuild publishes prebuilt binaries, they're compiled against a specific libc.
How do I fix "ENOTSUP"?
The ENOTSUP libc error occurs when npm packages with native binaries are built for glibc but your system uses musl (or vice versa). This commonly happens with Alpine Linux Docker images. Switch to a glibc-based image or rebuild packages from source.
What causes "ENOTSUP"?
Using Alpine Linux Docker image (musl-based) with packages built for glibc Package doesn't provide prebuilt binaries for musl libc Copying node_modules from a glibc system to a musl system
Is the "ENOTSUP" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading