Promote Alpine Linux out of experimental to be a tier 2 platform

@targos

What is the problem this feature will solve?

We currently have a significant number of users of Alpine Linux (Linux using musl as its libc implementation). For the direct tarballs from the unofficial builds server there are approximately 1000 downloads per hour for x64 plus about 25 per hour for arm. We do not currently have the figures for the container images on dockerhub but I would expect it to be quite high too.

Given the number of people using this build, I feel there is some justification for releasing this through the normal processes so it is made available in the same timescales as the other tier 1/2 platforms. This would allow security updates to be made available in a timely manner, and also help to reduce any lag visible to customers caused by delays to the release of the container images in the docker-node project which is currently gated by availability of alpine builds (I will also note that there is a proposal to decouple Alpine, but that would not solve the problem of potentially having a delay in getting updates into the hands of our Alpine users)

We should also bear in mind that it is quite likely that many users are not aware that Alpine is in experimental status and do not understand the implications of using this platform in production. While it may be clear to
someone pulling it form the unofficial-builds server - the clue being in the hostname - when viewed on dockerhub it does not look any different to the other platforms which shipped as "official" container images.

Superficially I would hope that it would be a low risk to add Alpine as the Linux/glibc on x64/aarch64 platforms are well-supported and any likely risk would be around its use of musl instead of the GNU libc. I'm not sure if we've ever hit any problems so far because of that difference but I don't recall anything.

Noting that Alpine/x64 is already part of the regular CI testing and therefore failures on that platform will get noticed, but as an experimental platform any CI failures would not currently block a release cycle.

While I'm not considering it as part of this proposal, I will state for background information that we have previously had Alpine/ppc64le and Alpine/s390x container images published by the docker-node project. Alpine/ppc64le was discontinued in the node 22 time frame and I am proposing doing the same for
Alpine/s390x.

What is the feature you are proposing to solve the problem?

Promote the Alpine builds from Experimental to Tier 2 so that it is a formal part of the release cycle. This would be at least for the x64 architecture as a minimum, but possibly also arm64.

For this we would want to have some commitment from at least one contributor willing to actively keep up to date with any problems on the platform so in part this is a call for volunteers to be able to handle any failures and ensure that new features can be enabled successfully on the platform. Typically we have found that when problems show up they do get looked at fairly quickly if people spot that the unofficial builds for Alpine are not generated properly. This change would also mean that the environment used in the CI for testing and the build environment would be consistent (Unofficial build environments are not automatically kept in sync with the systems for the equivalent platform in the CI and in fact the compilers used are currently not the same)

We have some Alpine/x64 systems in the CI but would need to evaluate capacity and also add extra systems for arm64 if we chose to promote that Alpine architecture out of experimental status too.

Regardless of whether we choose to promote Alpine, should we perhaps have a github platform team created of interested parties that can be tagged if any issues show up?

What alternatives have you considered?

Leave it as-is - an experimental platform with no formal support.
Put more disclaimers on the existing experimental builds which are shipped as "official" container images to dockerhub (either have it more obvious on the dockerhub UI, or build it in such a way that it puts some notice to the console on startup)
As far as options we also have the choice to do this for just x64 or also arm. I believe Alpine is now quite popular on the desktop for the many developers now using arm Mac desktop systems so this can also be discussed in this issue. I will also note that if we included arm64 we would likely add native arm64 machines in, as opposed to the current cross-compiled one on the unofficial-builds server however I will point out that we do not currently test Alpine/arm in the CI.

FYI @nodejs/build @targos @mcollina and maybe @RafaelGSS who has seen the impacts of Alpine being an experimental platform when the docker images don't always get published quickly.

The current list of platforms and their support category is listed in https://github.com/nodejs/node/blob/main/BUILDING.md#platform-list

A couple of previous discussions on the topic of platform tiers:

Process for determining supported platforms #8265 (Note: From 2016 but referenced the original addition of Alpine to the docker-node project!)
Drop smartos support? #43457 (Mostly ref: Smartos)

Put more disclaimers on the existing experimental builds which are shipped as "official" container images to dockerhub (either have it more obvious on the dockerhub UI, or build it in such a way that it puts some notice to the console on startup)

Are there any others besides Alpine?

IMO if we are covering it in node-test-commit-linux, which we are, then it is already de facto a Tier 2 platform anyway.

Are there any others besides Alpine?

no

IMO if we are covering it in node-test-commit-linux, which we are, then it is already de facto a Tier 2 platform anyway.

I'm not sure I'd agree with that, since if it failed and no-one fixed it, we could reasonably pull it out of the CI than block a release on it (which is the main difference in Tier 2) Compare with SmartOS, which is tier 2, but we have people we can call on to resolve problems there.

Putting it up to tier 2 would imply that we can call on someone to assist with fixing it and so it would be expected to always work. This issue is about identifying someone willing to do that.

https://ci.nodejs.org/job/node-test-commit-linux/ shows only x64 being tested with Alpine

For Alpine on arm64 there are no tests.

https://github.com/nodejs/node/blob/main/BUILDING.md#platform-list lists only x64 with musl and makes no statement about arm64 with musl

@sxa

@sxa

Should this be a TSC topic?

As far as Docker users of node:alpine are concerned, they are mostly completely unaware of the formal lack of support. Some have been using Alpine for years in production and might be very concerned if there were to be a formal announcement that there is no support, or even worse, that the Alpine images will no longer be built and published.

Docker uses node:alpine images in their tutorials. Is this perhaps an opportunity for sponsorship / cooperation on Alpine support for mutual benefit?

https://docs.docker.com/get-started/workshop/02_our_app/ uses node:24-alpine
https://docs.docker.com/guides/gha/ uses node:lts-alpine

The unofficial builds with musl are being widely used, implying a high level of reliance on these "Experimental" builds.

A search for non-Docker usage

https://github.com/search?q=%28%22https%3A%2F%2Funofficial-builds.nodejs.org%2Fdownload%2Frelease%22+AND+%22musl%22%29+NOT+is%3Aarchived+NOT+is%3Afork&type=code

shows 1.2k hits including:

tj/n node version manager
pnpm/pnpm package manager
microsoft/azure-pipelines-agent

https://github.com/search?q=%28%22node%3Aalpine%22+OR+%22node%3A22-alpine%22+OR+%22node%3A24-alpine%22+OR+%22node%3A26-alpine%22+OR+%22node%3Alts-alpine%22%29+NOT+is%3Aarchived+NOT+is%3Afork&type=code&p=5

for Docker usage shows 190k hits.

Contrary to what most search results on the comparison may say, we've seen significantly better performance in production with the alpine images than with the official debian ones. I've tried switching to debian a couple times over the last few years but it has always resulted in higher CPU/Memory usage and longer response times, so we've always gone back to alpine. Would be great to see alpine promoted, I think it is a great distro 👍🏻

We should also bear in mind that it is quite likely that many users are not aware that Alpine is in experimental status and do not understand the implications of using this platform in production.

I can tell you for a fact that people do not realize this. We have customers routinely asking why their installs do not work on Alpine. So much so, that we write specific instructions for these customers: https://github.com/newrelic/node-native-metrics/blob/ef3eb3e4fc69df71c30d36f9d180113d23e61644/README.md#musl-libc-systems

I'll be following this issue so that I can update that if need be.

Happy to volunteer as a point of contact for Alpine/musl triage if it helps move this forward.

Some context on what I can commit to:

Watching the Alpine x64 jobs in node-test-commit-linux and triaging failures (musl-specific or otherwise) within a reasonable turnaround so they don't block releases.
Helping investigate musl-vs-glibc divergences when they show up — I run Alpine in production and am comfortable poking at native/build issues.
Reproducing reported Alpine issues against the unofficial-builds environment vs. CI, which seems relevant given the compiler drift you mentioned.

A few questions before committing to scope:

For the initial Tier 2 promotion, is the intent to limit to x64 only and treat arm64 as a separate follow-up once CI capacity exists? That seems sensible given there's no Alpine/arm64 in CI today.
Is there an existing @nodejs/platform-alpine (or similar) team I should ask to be added to, or would creating one be part of this work? You floated that idea in the original post.
For aligning the unofficial-builds environment with the CI environment (compilers in particular) — is that a prerequisite for promotion, or something to tackle after?

Also +1 on keeping ppc64le/s390x Alpine out of scope here; agree with the direction in docker-node#2462.

@awbx

Hi @awbx ! It's great to read of your willingness to contribute and participate! Are you using node:*alpine* Docker images or are you using Alpine directly? Which of x64 / arm64 are you using in your environment? One or both?

@MikeMcC399

Hi @MikeMcC399, thanks!

I'm using the official node:*-alpine Docker images (predominantly node:22-alpine, with some 20-alpine and 18-alpine still around for older projects). Not running Alpine directly on bare metal.

Architecture-wise, both:

arm64 locally — I develop on an Apple Silicon Mac and run the same node:*-alpine images there.
x64 in production — most of my deployments pin platform: linux/amd64 in compose/k8s.

So I'd be most useful for x64 triage (the production target), but I can also reproduce arm64 issues locally on a real arm64 host rather than via cross-compile/emulation, which might be worth something given there's no Alpine/arm64 in CI today.

@awbx

@awbx That sounds very promising! You might like to join the related Slack channels listed on

https://github.com/nodejs/docker-node/blob/main/CONTRIBUTING.md#discussion-areas

and hopefully @sxa will be able to answer your questions!

@ncopa

@ncopa (Tagging you since I had a discussion with you about Alpine on RISC-V recently elsewhere and you might have some insight. PLus I think you shared a link to this issue too :-) ) - do you have a view on the lifecycle of Node.js LTS releases and Alpine versions. (Ref earlier comment in this issue). With the Node.js LTS cycle typically being longer than an Alpine release would it be better for us to tie to a specific Alpine versions through the Node.js LTS period even if that version is no longer supported in order to avoid any incompatibilities between musl versions, or update the Alpine version in our build CI when the Alpine version we use goes out of support.

I'm interested to hear if you're aware of what other projects might typically do in this regard. (See also the PR #63737 (comment) for another comment on the topic)

TL;DR for TSC:

* We need the Alpine team created: [Create platform team for Alpine/musl admin#1065](https://github.com/nodejs/admin/issues/1065)

* As requested I have created a PR for the upgrade to tier 2: [Promote Alpine/x64 to tier 2 #63737](https://github.com/nodejs/node/pull/63737)

* As per [my comment in this issue last week](https://github.com/nodejs/node/issues/62764#issuecomment-4681819583) we need to have a discussion about whether we lock the Alpine version that we build on during the course of our node releases (meaning that we will end up building on an unsupported version) or upgrade during the lifecycle of a Node.js. I'd probably lean towards locking it if we can.

* From a technical perspective the only work which should be needed for this to be activated (since it's already in node-test-commit) is for the build team to configure a release container for this and add it into the `iojs+release` job

* My current assumption is that we would do this across all active release lines (since we ship containers on all of them, and it would be messy to have it differ between versions)

* While it doesn't have to be done immediately for this to be completed it would be good it we can have some guidelines as to the requirements for elevating a platform to tier 2 for the future.

Maybe one other thing for the list is the "expected assets" to be updated like in nodejs/build#4319 for any of the releases that will start producing the musl artifacts

x64-musl builds for each supported Node.js release line 22, 24 & 26 have been promoted to the regular download site:

https://nodejs.org/download/release/latest-v22.x/node-v22.23.3-linux-x64-musl.tar.gz
https://nodejs.org/download/release/latest-v22.x/node-v22.23.3-linux-x64-musl.tar.xz
https://nodejs.org/download/release/latest-v24.x/node-v24.21.0-linux-x64-musl.tar.gz
https://nodejs.org/download/release/latest-v24.x/node-v24.21.0-linux-x64-musl.tar.xz
https://nodejs.org/download/release/latest-v26.x/node-v26.10.0-linux-x64-musl.tar.gz
https://nodejs.org/download/release/latest-v26.x/node-v26.10.0-linux-x64-musl.tar.xz

They are however still waiting to be declared Tier 2 supported (see #63737).

The prebuilt Node.js selection on https://nodejs.org/en/download does not yet offer x64-musl in the Linux drop-down.

#63737 has now landed, meaning that Alpine linux-x64-musl is now Tier 2.

linux-arm64-musl is still Experimental and relies on distribution through https://unofficial-builds.nodejs.org/download/

Should this issue be kept open? If there are still open actions, it may be more transparent to close this one and collect any open items in one or more new issues.

My opinion is that ARM should be treated as equally important as x86-64. It would be even more difficult to provide support if we have to say "well, core supports X and Y, but still not Z."

My opinion is that ARM should be treated as equally important as x86-64. It would be even more difficult to provide support if we have to say "well, core supports X and Y, but still not Z."

Should this be a separate new issue for clarity, requesting linux-arm64-musl Tier 2 support? There was also a comment at some stage suggesting that linux-arm64-musl Experimental support should be listed explicitly in the BUILDING > Platform list to document the current status.

Should this issue be kept open? If there are still open actions, it may be more transparent to close this one and collect any open items in one or more new issues.

I've been 50:50 on closing this before it's on the web site which is the final action that would be required to get parity with the others, but I've now raised nodejs/nodejs.org#9179 so let's see if we can get traction on that.

My opinion is that ARM should be treated as equally important as x86-64. It would be even more difficult to provide support if we have to say "well, core supports X and Y, but still not Z."

Should this be a separate new issue for clarity, requesting linux-arm64-musl Tier 2 support?

IMHO, yes if it's desired but please bear in mind it's not just a matter of flicking a switch to make it happen. Arm/musl was mentioned in my initial description of this issue as well as some of the potential blockers for doing it alongside arm (For one thing we have no systems for testing it at present whereas we did for x64 so it couldn't be done alongside this). While I would be in favour of having them, we shouldn't do it under this and I'm not sure I want to be the one driving it forward.

In the meantime we do publish experimental builds for arm64-musl in the unofficial-builds project but those should not be considered supported in any way.

Also I'm not quite sure about what you mean regarding teh "Well, core supports X and Y but still not Z" statement as that could be true for any number of other platforms that are not tier 1/2.

I've been 50:50 on closing this before it's on the web site which is the final action that would be required to get parity with the others, but I've now raised nodejs/nodejs.org#9179 so let's see if we can get traction on that.

I did take a look at this previously and realized it's not a simple update, so I stayed quiet! 🙂 It's not a prerequisite for using the builds for docker-node. It's good that you've set the ball rolling though. 👍🏻

Should this be a separate new issue for clarity, requesting linux-arm64-musl Tier 2 support?

I am tracking this issue to determine when I can revise my support statements and update a package that needs this. To me, this issue is incomplete if the platforms Alpine supports, and users expect to be able to use, are not considered supported.

Also I'm not quite sure about what you mean regarding teh "Well, core supports X and Y but still not Z" statement as that could be true for any number of other platforms that are not tier 1/2.

See my original post above in support of this effort: #62764 (comment)

Right now, I am able to say "sorry, core does not support Alpine." If this issue gets "resolved" by only supporting x64, I then have to say "sorry, core supports Alpine, but only on x64." This complicates both telling customers what is possible and building/supplying artifacts (native modules).

I then have to say "sorry, core supports Alpine, but only on x64."

I think that's reasonable and reflects what we are able to do at the moment. We don't support every architecture that glibc Linux runs on, and the same is true of Alpine (In the past we previously published alpine container images on ppc64le and s390x as well as the other two which were similarly unsupported). On your previous comment that you referenced (unless I'm mistaken) that was specifically about the impression of support being given by the container images being published to dockerhub which is a separate issue for the containers project that can be discussed in nodejs/docker-node#2011.

While I'd prefer not to resolve the support question by stopping publishing the Alpine/aarch64 images completely (which is what we've done for ppc64le and s390x I will reiterate that at the moment the project do not have the prerequisite things in place to support anything other than x64 at present and I do not intend to push that forward myself, however now that we have been able to put the processes in place under this issue to support x64 builds and prove that it works it gives us a foundation that we may be able to build from in the future, which should be covered in separate issues if desired.

@sxa

I've split off the request for Alpine Linux arm64 / musl Tier 2 support into a new issue #66394 for clarity. If you have an interest in seeing this implemented you can upvote the issue.

As @sxa already mentioned, it's not just a case of switching support on. It has significant impact and risks.

From a practical point of view, the Alpine Linux Docker images for arm64 have not been reported as being problematic at all, so although they don't have official Tier 2 support status, they do seem to work all right!

Navigation Menu

Repository navigation

Promote Alpine Linux out of experimental to be a tier 2 platform #62764

What is the problem this feature will solve?

What is the feature you are proposing to solve the problem?

What alternatives have you considered?

10 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Promote Alpine Linux out of experimental to be a tier 2 platform #62764

Description

What is the problem this feature will solve?

What is the feature you are proposing to solve the problem?

What alternatives have you considered?

Activity

Renegade334 commented on May 2, 2026

mcollina commented on May 2, 2026

sxa commented on May 7, 2026

MikeMcC399 commented on May 11, 2026

MikeMcC399 commented on May 12, 2026

MikeMcC399 commented on May 13, 2026

caseywebdev commented on May 13, 2026

jsumners-nr commented on May 19, 2026

awbx commented on May 19, 2026

MikeMcC399 commented on May 20, 2026

awbx commented on May 20, 2026

MikeMcC399 commented on May 20, 2026

10 remaining items

sxa commented on Jun 30, 2026

nschonni commented on Jul 5, 2026

MikeMcC399 commented on Sep 24, 2026

MikeMcC399 commented on Sep 28, 2026

jsumners-nr commented on Sep 28, 2026

MikeMcC399 commented on Sep 29, 2026

sxa commented on Sep 29, 2026

sxa commented on Sep 29, 2026

MikeMcC399 commented on Sep 29, 2026

jsumners-nr commented on Sep 29, 2026

sxa commented on Sep 29, 2026

MikeMcC399 commented on Sep 29, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions