nodejs/docker-node

Node.js

node - Docker Official Images on Docker Hub

The official Node.js docker image, made with love by the node community.

Table of Contents

• What is Node.js?
• How to use this image
  • Create a Dockerfile in your Node.js app project
  • Best Practices
  • Run a single Node.js script
  • npm loglevel
    • Dockerfile
    • Docker Run
    • npm run
• Image Variants
  • node:<version>
  • node:lts
  • node:alpine
  • node:bullseye
  • node:bookworm
  • node:trixie
  • node:slim
• Long Term Support (LTS)
• Release Availability
• License
• Supported Docker versions
• Supported Node.js versions
• Supported architectures
  • musl builds for Alpine
• Yarn v1 Classic bundling
• Governance and Current Members
  • Docker Maintainers
  • Collaborators
  • Emeritus

What is Node.js?

Node.js is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices.

See: https://nodejs.org

How to use this image

Create a Dockerfile in your Node.js app project

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

You can then build and run the Docker image:

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

If you prefer Docker Compose:

services:
  node:
    image: 'node:24'
    user: 'node'
    working_dir: /home/node/app
    environment:
      - NODE_ENV=production
    volumes:
      - ./:/home/node/app
    ports: # use if it is necessary to expose the container to the host machine
      - '8888:8888'
    command: ['npm', 'start']

You can then run using Docker Compose:

$ docker-compose up -d

Docker Compose example mounts your current directory (including node_modules) to the container. It assumes that your application has a file named package.json defining start script.

Best Practices

We have assembled a Best Practices Guide for those using these images on a daily basis.

Run a single Node.js script

For many simple, single file projects, you may find it inconvenient to write a complete Dockerfile. In such cases, you can run a Node.js script by using the Node.js Docker image directly:

$ 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

npm loglevel

The default npm loglevel is notice, which includes also the levels warn and error. If you need to set a different loglevel for npm, follow these example instructions:

Dockerfile

If you create your own Dockerfile which inherits from the node image, you can use ENV to set the NPM_CONFIG_LOGLEVEL environment variable.

FROM node:lts
ENV NPM_CONFIG_LOGLEVEL=info
...

Docker Run

If you run the node image using docker run, you can use the -e flag to set the NPM_CONFIG_LOGLEVEL environment variable.

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

npm run

If you are running npm commands, you can use the --loglevel command line flag to control the verbosity of the output.

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

Image Variants

The node images come in many flavors, each designed for a specific use case. All of the images contain pre-installed versions of node which includes also npm. For each supported architecture, the supported variants are different. In the file: versions.json, it lists all supported variants for all of the architectures that we support now.

The legacy package manager Yarn v1 Classic is included in node images with Node.js 25 and below. See Yarn v1 Classic bundling for details.

View the list of currently supported floating and pinned tags on Docker Hub.

node:<version>

This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. This tag is based off of buildpack-deps. buildpack-deps is designed for the average user of docker who has many images on their system. It, by design, has a large number of extremely common Debian packages. This reduces the number of packages that images that derive from it need to install, thus reducing the overall size of all images on your system.

node:lts

This is a special form of node:<version> that selects the Active Long Term Support version of Node.js. See also Long Term Support below for more detail.

node:alpine

This image is based on Alpine Linux. Because base alpine images are smaller than corresponding base debian images, the resulting node:alpine Docker images are around 25% smaller than the Debian-based node:slim images.

Alpine images use the C library musl libc, not the GNU C library glibc used by Debian.

Generally, applications written for Debian (glibc) will not run under Alpine (musl). Some compatibility issues may be resolvable by installing the Alpine gcompat GNU C Library compatibility layer for musl package. Use apk add --no-cache gcompat to install.

Tools such as git or bash are not included in node:alpine* based images. The Alpine documentation describes how to find and install additional packages using apk (Alpine Package Keeper).

The Best Practices document, in the section Smaller images without npm/yarn, shows how to produce a custom image by removing package managers in a multi-stage build.

node:bullseye

This image is based on version 11 of Debian, available in the debian official image.

node:bookworm

This image is based on version 12 of Debian, available in the debian official image.

node:trixie

This image is based on version 13 of Debian, available in the debian official image.

node:slim

This image does not contain the common packages contained in the default tag and only contains the minimal packages needed to run node. Unless you are working in an environment where only the Node.js image will be deployed and you have space constraints, we highly recommend using the default image of this repository.

Long Term Support (LTS)

Production applications should only use LTS releases.

Refer to Node.js Releases for a description of release phases and schedule.

If no version selection is made in a tag, for example, node:slim, then the Current release is selected. node images using the Active LTS release are published with an lts floating tag to aid their selection. node:lts can be used on its own, or in combination with other tags such as node:lts-slim. To select a node image based on a Maintenance LTS version use the literal node version in the tag.

Release Availability

This repo automatically triggers a process to build new node images when Node.js releases become available. The build processes can take several hours to complete.

Images may initially appear on Docker Hub with incomplete or missing OS/ARCH listings as the build process first publishes a tag and then backfills each architecture when ready. During this time, if you try to pull the image, you may see an error message "no matching manifest". In this case, check back later. (See Docker Library FAQs for a detailed description of the complex build process.)

For Node.js security releases, Debian-based node images may be published in advance of Alpine-based images. To build an Alpine-based node image requires a musl build. This may not initially be ready at Node.js release time. When processing non-security Node.js releases, the build process will wait for the musl build before proceeding with Debian- and Alpine-based images.

License

License information for the software contained in this image. License information for the Node.js Docker project.

Supported Docker versions

If you are using Docker Desktop, it is recommended to use a recent version, released in the last six months.

Refer to Docker Engine release notes for current Engine versions.

Supported Node.js versions

Support for node Docker images is limited to Node.js active versions.

Before opening an issue in this repo, please consider if the problem only occurs in a node Docker environment.

If a problem can also be reproduced without using an image from this repo, for example in a non-Docker environment, then it should be reported to the corresponding component.

Use the Node.js issues or the npm issues list to check for known issues or to report new issues for these components.

Supported architectures

node images are built for the Linux operating system and architecture combinations defined in versions.json.

• The Node.js Platform list defines Support Tiers 1, 2 and Experimental for platform and architecture combinations of Node.js builds and for each separate Node.js release line
• The Docker official images library lists the supported architectures in the Docker build environment

Each of the architectures for Debian images belong to the Node.js support tier 1 or 2, recommended for production applications.

musl builds for Alpine

musl builds for amd64 are listed under support tier "Experimental" and are tested by the Node.js build process before being used in Docker images. "Experimental" status for Node.js is defined as:

Experimental: May not compile or test suite may not pass. The core team does not create releases for these platforms. Test failures on experimental platforms do not block releases. Contributions to improve support for these platforms are welcome.

musl builds for other architectures, including arm64, are not tested before release.

Yarn v1 Classic bundling

The Yarn v1 Classic package manager is bundled in node image variants that include Node.js versions 25 and below.

Yarn v1 is not bundled into node images as of Node.js 26.0.0. This version of the Yarn package manager has been declared as frozen and is no longer maintained.

Users with legacy requirements for Yarn v1 under Node.js 26 and above may be able to follow Yarn v1 installation instructions and install using npm install --global yarn.

Governance and Current Members

The Node.js Docker Image is governed by an open maintainer model. See GOVERNANCE.md for project roles and decision-making, and CONTRIBUTING.md for contribution guidance. If a final decision cannot be reached using consensus seeking, the Node.js TSC is the final arbiter.

Docker Maintainers

• Simen Bekkhus (SimenB)
• Peter Dave Hello (PeterDaveHello)
• Rafael Gonzaga (rafaelgss)
• Matteo Collina (mcollina)
• Nick Schonning (nschonni)

Collaborators

• Laurent Goderre (LaurentGoderre)
• Tianon Gravi (tianon)
• yosifkit
• Stewart X Addison (sxa)
• Mike McCready (MikeMcC399)

Collaborators are managed via the @nodejs/docker team.

Emeritus

• Hans Kristian Flaatten (Starefossen)
• Mikeal Rogers (mikeal)
• Christopher Horrell (chorrell)
• Peter Petrov (pesho)
• John Mitchell (jlmitch5)
• Hugues Malphettes (hmalphettes)
• ttshivers (ttshivers)