Do not promote docker alpine image in the website

The Alpine Docker image for Node.js is experimental, as Node.js does not fully support MUSL (though it works reasonably well there).

We should stop promoting this.

which image should we promote instead ?

As of today, I recommend using the -slim versions.

cc @nodejs/tsc

I think my opinion on this topic is clear, we should not be actively promoting Alpine like this (I'd rather it wasn't an official docker image but that's a separate discussion) until such time as it is able to be promoted out of experimental. I don't see anyone stepping up to do that, so this change would absolutely be a 👍🏻 from me. But wow, I hadn't spotted that it was in there!

Maybe also link to https://github.com/nodejs/docker-node for more information, since there are many variants available.

Although -slim is probably the nearest non-experimental equivalent to -alpine, perhaps just the default would have wider applicability? For instance node:24 which is equivalent to node:24-bookworm.

@mcollina

@mcollina

As of today, I recommend using the -slim versions.

That would seem to contradict the recommendation in https://github.com/nodejs/docker-node/blob/main/README.md#nodeslim which says:

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.

Then let's just use the default image.

Then let's just use the default image.

Very good!

I'm just looking at the documentation for the default image in https://github.com/nodejs/docker-node/blob/main/README.md#nodeversion and I'll soon submit a PR to propose making the description of the default image a bit clearer.

Then let's just use the default image.

I don't feel comfortable setting a 400+MB image by default for an environment that should only contain Node.js. I'm happy switching to -slim but 👎 to switching to the full image. People aren't going to run development environments inside the containers mostly (or are they) -- we also haven't gotten anyone complaining about the -alpine image. Since it is experimental, sure, let's get to one of the supported ones. But I'd lean into -slim.

If the goal is only to deliver Node.js in a minimal Docker Debian environment, then -slim is the best choice. 24-trixie-slim is 77 MB compressed for amd64. 24-trixie is 418 MB compressed.

Each of the two variants have their uses, and only end-users can decide which one is appropriate for them. To that end, if the text could also include a link to the https://github.com/nodejs/docker-node#readme that would give users access to the information to allow them to make their own choices about which image they want to use.

The significantly larger size of the default image is caused by basing it on buildpack-deps, as explained in the README:

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.

The compressed size difference between trixie-slim (28 MB) and trixie (47 MB) base Debian images (that don't contain Node.js) is only ~20 MB.

👍 I'd be in favor of switching to -slim, that seems in the best interests of our users -- no risk of compatibility/support issues, while also being a lighter-weight base image for just getting a Node.js application up and running.

@MattIPv4

Agree with @MattIPv4 and also fine adding a tiny footnote "For more details on Node.js on Docker read this" pointing to the nodejs/docker-node readme :)

nodejs.org/apps/site/snippets/en/download/docker.bash

Line 5 in 8b76115

    
           docker pull node:${props.release.major}-${props.release.major >= 4 ? 'alpine' : 'slim'}

was already using slim for Node.js < 4, so perhaps that condition can just be taken out and use slim for all versions?

Feel free to open a PR :)

Feel free to open a PR :)

Done! See #8784 - my first PR for this repo.

Navigation Menu

Repository navigation

Do not promote docker alpine image in the website #8690

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Do not promote docker alpine image in the website #8690

Description

Activity

AugustinMauroy commented on Mar 3, 2026

mcollina commented on Mar 3, 2026

mcollina commented on Mar 3, 2026

sxa commented on Mar 3, 2026

MikeMcC399 commented on Mar 3, 2026

MikeMcC399 commented on Mar 4, 2026

mcollina commented on Mar 4, 2026

MikeMcC399 commented on Mar 4, 2026

ovflowd commented on Mar 6, 2026

MikeMcC399 commented on Mar 6, 2026

MattIPv4 commented on Mar 6, 2026

ovflowd commented on Mar 6, 2026

MikeMcC399 commented on Mar 29, 2026

ovflowd commented on Mar 29, 2026

MikeMcC399 commented on Mar 29, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions