nodejs/docker-node: The Official Node.js Docker Image with Alpine, Slim, and Debian Variants

What nodejs/docker-node Provides and Who Uses It

nodejs/docker-node is the upstream repository that generates the official 'node' image published to Docker Hub at hub.docker.com/_/node. It is maintained by Node.js community members and contains the Dockerfile templates, version configuration files, and automation scripts that produce each tagged image.

The audience spans several groups. Application developers who need to containerize a Node.js application use the images directly in their own Dockerfiles by writing FROM node:<version>. CI/CD engineers use the images as the base for build and test environments. Infrastructure teams use the images to standardize the runtime across deployments.

The repository itself is less useful to read than to understand. Most users interact with the images on Docker Hub rather than the source Dockerfile templates. The repository is relevant when you need to understand exactly what is in an image, need to report or check a security issue, or want to understand the image build automation.

Image Variants and When to Use Each

The repository produces several image variants for each Node.js version. The README documents these in a dedicated section.

node:<version> is the default image. It is based on buildpack-deps, which is a Debian-based image that includes a large number of common Debian packages. This reduces the number of additional packages that derived images need to install. The README describes this as the image for users who are unsure what they need.

node:lts is a floating tag that always points to the active Long Term Support version of Node.js. This is the recommended choice for production applications that want to track the stable supported release without pinning to a specific version number.

node:alpine is based on Alpine Linux and is approximately 25% smaller than node:slim according to the README. The trade-off is that Alpine uses musl libc instead of the GNU C library (glibc) that Debian images use.

node:slim is a trimmed version of the Debian-based image that removes some packages included by default. It is larger than node:alpine but uses glibc.

node:bookworm and node:trixie are Debian release-specific variants for teams that need to pin to a specific Debian version.

The supported variants for each architecture are listed in versions.json in the repository.

Writing a Dockerfile with the node Image

The README shows the minimal Dockerfile for a Node.js application:

# specify the node base image with your desired version node:<version>
FROM node:24
# replace this with your application's default port
EXPOSE 8888

After writing the Dockerfile, you build and run it:

$ docker build -t my-nodejs-app .
$ docker run -it --rm --name my-running-app my-nodejs-app

For environments that prefer Docker Compose, the README shows a full service definition:

services:
  node:
    image: 'node:24'
    user: 'node'
    working_dir: /home/node/app
    environment:
      - NODE_ENV=production
    volumes:
      - ./:/home/node/app
    ports:
      - '8888:8888'
    command: ['npm', 'start']

The Compose example mounts the current directory into /home/node/app inside the container and sets NODE_ENV to production. It assumes the application has a package.json with a start script.

For single-file scripts that do not warrant a full Dockerfile, the README shows running a script directly against the image:

$ docker run -it --rm --name my-running-script -v "$PWD":/usr/src/app -w /usr/src/app node:24 node your-daemon-or-script.js

Alpine vs. Debian: The musl/glibc Trade-off

The choice between node:alpine and node:slim or node:bookworm is a choice between two C library implementations: musl (Alpine) and glibc (Debian). The README is explicit about this trade-off.

Applications written for Debian (glibc) will not run under Alpine (musl). The README states this directly: Generally, applications written for Debian (glibc) will not run under Alpine (musl). Some compatibility issues may be resolvable by installing the Alpine gcompat package, which provides GNU C Library compatibility.

Practical implications: native Node.js modules that include compiled binaries may fail on Alpine if the binary was compiled against glibc. npm packages that use native extensions are particularly susceptible to this. Before switching an existing application to node:alpine, test all native dependencies in the Alpine environment.

The README notes that Alpine images are around 25% smaller than node:slim images. For applications with no native dependencies and where image size matters, node:alpine is a good choice. For applications with native modules, start with node:slim or node:bookworm.

The musl builds for Alpine are explicitly mentioned in the README as a separate architectural consideration, with a note that all supported Alpine variants follow the same musl constraint.

npm Loglevel and Environment Configuration

The README documents three ways to configure npm's log level when using the official images.

In a Dockerfile that inherits from the node image, you can use the ENV instruction:

FROM node:lts
ENV NPM_CONFIG_LOGLEVEL=info

When running the node image with docker run, the -e flag sets the environment variable:

$ docker run -e NPM_CONFIG_LOGLEVEL=info node:lts ...

When running npm commands inside a container, the --loglevel flag works directly:

$ docker run node:lts npm --loglevel=info ...

The default npm log level is 'notice', which includes 'warn' and 'error' levels. In CI environments where verbose output is helpful for debugging, setting this to 'info' or 'verbose' is common. In production images where log noise is a concern, 'warn' or 'error' is more appropriate.

Limitations: Image Size, Yarn v1, and Architecture Variants

The default node:<version> image is large because it inherits from buildpack-deps, which includes many common build tools. For production deployments where image size affects pull time and storage, the full image is rarely the right choice. The slim and alpine variants address this, but with the trade-offs described above.

Yarn v1 Classic is included in node images for Node.js 25 and below, according to the README. Images for Node.js 26 and higher do not bundle Yarn v1. If your project depends on Yarn v1, you need to verify which image versions include it or install it separately.

Not all image variants are available for all architectures. The README states that for each supported architecture, the supported variants are different. The versions.json file in the repository lists what is actually supported. This matters for teams deploying to ARM64 (Apple Silicon, Graviton) or other non-x86 architectures.

The repository has no GitHub releases. Updates are made directly to the main branch and Dockerfile templates.

nodejs/docker-node vs. Building Your Own Base Image

Building a custom base image starting from scratch or from a minimal Debian or Alpine image gives complete control over what is installed, which is useful for security-conscious teams that want to minimize the attack surface. This approach requires maintaining the base image through Node.js version updates manually, including security patches, certificate updates, and Node.js LTS transitions.

The official image is maintained by the Node.js community and is updated when new Node.js versions are released. It includes a governance structure documented in GOVERNANCE.md and a list of Docker Maintainers and Collaborators in the README. The maintenance burden falls on the upstream project rather than your team.

For most teams, the official image is the correct starting point. Custom base images make sense only when the official variants do not meet specific requirements that cannot be addressed through environment variables or a thin derived Dockerfile layer. The Best Practices Guide in docs/BestPractices.md provides additional guidance for production deployments, including recommendations on non-root users, file permissions, and signal handling.

Editorial conclusion

The official Node.js Docker image is the right starting point for nearly all Node.js container workloads. Engineers who need minimal images should use node:alpine but verify glibc compatibility first, since Alpine uses musl libc and applications compiled against glibc will not run without remediation. Teams that must pin to a specific Debian release should use node:bookworm or node:trixie. Check versions.json in the repository to confirm which variants are supported for your target architecture before building.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nodejs/docker-node on GitHub
4. Project website
5. README