Skip to content

BUILDING.md

Latest commit

 

History

History
1165 lines (865 loc) · 43.7 KB

BUILDING.md

File metadata and controls

1165 lines (865 loc) · 43.7 KB
Raw

Building Node.js

Depending on what platform or features you need, the build process may differ. After you've built a binary, running the test suite to confirm that the binary works as intended is a good next step.

If you can reproduce a test failure, search for it in the Node.js issue tracker or file a new issue.

Table of contents

Supported platforms

This list of supported platforms is current as of the branch/release to which it belongs.

Input

Node.js relies on V8 and libuv. We adopt a subset of their supported platforms.

Strategy

There are three support tiers:

  • Tier 1: These platforms represent the majority of Node.js users. The Node.js Build Working Group maintains infrastructure for full test coverage. Test failures on tier 1 platforms will block releases.
  • Tier 2: These platforms represent smaller segments of the Node.js user base. The Node.js Build Working Group maintains infrastructure for full test coverage. Test failures on tier 2 platforms will block releases. Infrastructure issues may delay the release of binaries for these platforms.
  • 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.

Platforms may move between tiers between major release lines. The table below will reflect those changes.

Platform list

Node.js compilation/execution support depends on operating system, architecture, and libc version. The table below lists the support tier for each supported combination. A list of supported compile toolchains is also supplied for tier 1 platforms.

For production applications, run Node.js on supported platforms only (Tier 1 or 2).

Node.js does not support a platform version if a vendor has expired support for it. In other words, Node.js does not support running on End-of-Life (EoL) platforms. This is true regardless of entries in the table below.

Operating System Architectures Versions Support Type Notes
GNU/Linux x64 kernel >= 4.181, glibc >= 2.28 Tier 1 e.g. Ubuntu 20.04, Debian 10, RHEL 8
GNU/Linux x64 kernel >= 3.10, musl >= 1.1.19 Experimental e.g. Alpine 3.8
GNU/Linux x86 kernel >= 3.10, glibc >= 2.17 Experimental Downgraded as of Node.js 10
GNU/Linux arm64 kernel >= 4.181, glibc >= 2.28 Tier 1 e.g. Ubuntu 20.04, Debian 10, RHEL 8
GNU/Linux armv7 kernel >= 4.181, glibc >= 2.28 Experimental Downgraded as of Node.js 24
GNU/Linux ppc64le >=power9 kernel >= 4.181, glibc >= 2.28 Tier 2 e.g. Ubuntu 20.04, RHEL 8
GNU/Linux s390x >=z14 kernel >= 4.181, glibc >= 2.28 Tier 2 e.g. RHEL 8
GNU/Linux loong64 kernel >= 5.19, glibc >= 2.36 Experimental
GNU/Linux riscv64 kernel >= 5.19, glibc >= 2.36 Experimental GCC >= 14 or Clang >= 19 for native builds2
Windows x64 >= Windows 10/Server 2016 Tier 1 3,4
Windows arm64 >= Windows 10 Tier 2
macOS x64 >= 13.5 Tier 2 Until early 20285. For notes about compilation see 6
macOS arm64 >= 13.5 Tier 1
SmartOS x64 >= 18 Tier 2
AIX ppc64be >=power9 >= 7.2 TL04 Tier 2
FreeBSD x64 >= 13.2 Experimental
OpenHarmony arm64 >= 5.0 Experimental

Supported toolchains

Depending on the host platform, the selection of toolchains may vary.

Operating System Compiler Versions
Linux GCC >= 13.2 or Clang >= 19.1
Windows Visual Studio 2022 or 2026 with the Windows 11 SDK on a 64-bit host
macOS Xcode >= 16.4 (Apple LLVM >= 19)

Official binary platforms and toolchains

Binaries at https://nodejs.org/download/release/ are produced on:

Binary package Platform and Toolchain
aix-ppc64 AIX 7.2 TL04 on PPC64BE with Clang 20.1
darwin-x64 macOS 15, Xcode 16 with -mmacosx-version-min=13.5
darwin-arm64 (and .pkg) macOS 15 (arm64), Xcode 16 with -mmacosx-version-min=13.5
linux-arm64 RHEL 8 with Clang 20.1 and gcc-toolset-14-libatomic-devel7
linux-ppc64le RHEL 8 with Clang 20.1 and gcc-toolset-14-libatomic-devel7
linux-s390x RHEL 8 with Clang 20.1 and gcc-toolset-14-libatomic-devel7
linux-x64 RHEL 8 with Clang 20.1 and gcc-toolset-14-libatomic-devel7
win-arm64 Windows Server 2022 (x64) with Visual Studio 2022
win-x64 Windows Server 2022 (x64) with Visual Studio 2022

Starting with Node.js 25, official Linux binaries are linked with libatomic and these systems must have the libatomic runtime installed and available at execution time to run the binaries. The package name for the libatomic runtime is typically libatomic or libatomic1 depending on your Linux distribution.

OpenSSL asm support

OpenSSL-1.1.1 requires the following assembler version for use of asm support on x86_64 and ia32.

For use of AVX-512,

  • gas (GNU assembler) version 2.26 or higher
  • nasm version 2.11.8 or higher in Windows

AVX-512 is disabled for Skylake-X by OpenSSL-1.1.1.

For use of AVX2,

  • gas (GNU assembler) version 2.23 or higher
  • Xcode version 5.0 or higher
  • llvm version 3.3 or higher
  • nasm version 2.10 or higher in Windows

Please refer to https://docs.openssl.org/1.1.1/man3/OPENSSL_ia32cap/ for details.

If compiling without one of the above, use configure with the --openssl-no-asm flag. Otherwise, configure will fail.

Previous versions of this document

Supported platforms and toolchains change with each major version of Node.js. This document is only valid for the current version of Node.js, and is expected to be valid for the entire lifetime of this release line.

To consult the version of this document for another version, download its source tarball and/or browse the git repository checked out at the relevant tag.

Building Node.js on supported platforms

Prerequisites

Unix and macOS

Unix prerequisites

  • gcc and g++ >= 13.2 or clang and clang++ >= 19.1
  • GNU Make 3.81 or newer
  • A supported version of Python
    • For test coverage, your Python installation must include pip.

Installation via Linux package manager can be achieved with:

  • Nix, NixOS: nix-shell
  • Ubuntu, Debian: sudo apt-get install python3 g++-13 gcc-13 make python3-pip
  • Fedora: sudo dnf install python3 gcc-c++ make python3-pip
  • CentOS and RHEL: sudo yum install python3 gcc-c++ make python3-pip
  • OpenSUSE: sudo zypper install python3 gcc-c++ make python3-pip
  • Arch Linux, Manjaro: sudo pacman -S python gcc make python-pip

FreeBSD and OpenBSD users may also need to install libexecinfo.

macOS prerequisites

macOS users can install the Xcode Command Line Tools by running xcode-select --install. Alternatively, if you already have the full Xcode installed, you can find them under the menu Xcode -> Open Developer Tool -> More Developer Tools.... This step will install clang, clang++, and make.

Nix integration

If you are using Nix and direnv, you can use the following to get started:

echo 'use_nix --arg sharedLibDeps {} --argstr icu small' > .envrc
direnv allow .
make build-ci -j12

Most dependencies will likely be available in the official nixpkgs cache, although for some dependencies we have to deviate for the upstream repository, in which case those will be built locally, or you can use the Cachix repository for the project: cachix use nodejs. See https://docs.cachix.org/ for more information.

The use of make build-ci is to ensure you are using the CONFIG_FLAGS environment variable. You can also specify it manually:

./configure $CONFIG_FLAGS
make -j12

Passing the --arg sharedLibDeps {} instructs direnv and Nix to generate an environment that uses the vendored-in native dependencies. Using the vendored-in dependencies result in a result closer to the official binaries, the tradeoff being the build will take longer to complete as you'd have to build those dependencies instead of using the cached ones from the Nix cache. You can omit that flag to use all the shared dependencies, or specify only some dependencies:

cat -> .envrc <<'EOF'
use nix --arg sharedLibDeps '{
  inherit (import ./tools/nix/sharedLibDeps.nix {})
    openssl
    zlib
  ;
}'
EOF

Passing the --argstr icu small instructs direnv and Nix to pass --with-intl=small in the CONFIG_FLAGS environment variable. If you omit this, the prebuilt ICU from Nix cache will be used, which should speed up greatly compilation time.

The use of direnv is completely optional, you can also use nix-shell directly, e.g. here's a command you can use to build a binary for benchmarking purposes:

# Passing `--arg loadJSBuiltinsDynamically false` to instruct the compiler to
# embed the JS core files so it is no longer affected by local changes
# (necessary for getting useful benchmark results).
# Passing `--arg devTools '[]' --arg benchmarkTools '[]'` since we don't need
# those to build node.
nix-shell \
  --arg loadJSBuiltinsDynamically false \
  --arg devTools '[]' --arg benchmarkTools '[]' \
  --run 'make build-ci -j12'

mv out/Release/node ./node_old

# ...
# Make your local changes, and re-build node

nix-shell \
  --arg loadJSBuiltinsDynamically false \
  --arg devTools '[]' --arg benchmarkTools '[]' \
  --run 'make build-ci -j12'

nix-shell --pure --run './node benchmark/compare.js --old ./node_old  --new ./node http | Rscript benchmark/compare.R'

There are additional attributes you can pass, see shell.nix file for more details.

Building Node.js

If the path to your build directory contains a space, the build will likely fail.

To build Node.js:

./configure
make -j4

Important

If you face a compilation error during this process such as error: no matching conversion for functional-style cast from 'unsigned int' to 'TypeIndex' Make sure to use a g++ or clang version compatible with C++20.

We can speed up the builds by using Ninja. For more information, see Building Node.js with Ninja.

The -j4 option will cause make to run 4 simultaneous compilation jobs which may reduce build time. For more information, see the GNU Make Documentation.

The above requires that python resolves to a supported version of Python. See Prerequisites.

After building, setting up firewall rules can avoid popups asking to accept incoming network connections when running tests.

Running the following script on macOS will add the firewall rules for the executable node in the out directory and the symbolic node link in the project's root directory.

sudo ./tools/macos-firewall.sh

Installing Node.js

To install this version of Node.js into a system directory:

[sudo] make install

Running tests

To verify the build:

make test-only

At this point, you are ready to make code changes and re-run the tests.

If you are running tests before submitting a pull request, use:

make -j4 test

make -j4 test does a full check on the codebase, including documentation tests.

To run the linter, use make lint/vcbuild lint. It will lint JavaScript, C++, and Markdown files.

To fix auto fixable JavaScript linting errors, use make lint-js-fix.

If you are updating tests and want to run tests in a single test file (e.g. test/parallel/test-stream2-transform.js):

tools/test.py test/parallel/test-stream2-transform.js

You can execute the entire suite of tests for a given subsystem by providing the name of a subsystem:

tools/test.py child-process

You can also execute the tests in a test suite directory (such as test/message):

tools/test.py test/message

You can execute tests that match a specific naming pattern using the wildcard *. For example, to run all tests under test/parallel with a name that starts with test-stream-:

tools/test.py test/parallel/test-stream-*
tools/test.py parallel/test-stream-*  # The test/ prefix can be omitted
# In some shell environments, you may need to quote the pattern
tools/test.py "test/parallel/test-stream-*"

The wildcard * can be used in any part of the path. For example, to run all tests with a name that starts with test-inspector-, regardless of the directory they are in:

# Matches test/sequential/test-inspector-*, test/parallel/test-inspector-*,
# test/known_issues/test-inspector-*, etc.
tools/test.py "test/*/test-inspector-*"
tools/test.py "*/test-inspector-*"  # The test/ prefix can be omitted

If you want to check the other options, please refer to the help by using the --help option:

tools/test.py --help

Note: On Windows you should use python3 executable. Example: python3 tools/test.py test/message

You can usually run tests directly with node:

./node test/parallel/test-stream2-transform.js

Info: ./node points to your local Node.js build.

Remember to recompile with make -j4 in between test runs if you change code in the lib or src directories.

The tests attempt to detect support for IPv6 and exclude IPv6 tests if appropriate. If your main interface has IPv6 addresses, then your loopback interface must also have '::1' enabled. For some default installations on Ubuntu, that does not seem to be the case. To enable '::1' on the loopback interface on Ubuntu:

sudo sysctl -w net.ipv6.conf.lo.disable_ipv6=0

You can use node-code-ide-configs to run/debug tests if your IDE configs are present.

Running coverage

It's good practice to ensure any code you add or change is covered by tests. You can do so by running the test suite with coverage enabled:

./configure --coverage
make coverage

A detailed coverage report will be written to coverage/index.html for JavaScript coverage and to coverage/cxxcoverage.html for C++ coverage.

If you only want to run the JavaScript tests then you do not need to run the first command (./configure --coverage). Run make coverage-run-js, to execute JavaScript tests independently of the C++ test suite:

make coverage-run-js

If you are updating tests and want to collect coverage for a single test file (e.g. test/parallel/test-stream2-transform.js):

make coverage-clean
NODE_V8_COVERAGE=coverage/tmp tools/test.py test/parallel/test-stream2-transform.js
make coverage-report-js

You can collect coverage for the entire suite of tests for a given subsystem by providing the name of a subsystem:

make coverage-clean
NODE_V8_COVERAGE=coverage/tmp tools/test.py --mode=release child-process
make coverage-report-js

The make coverage command downloads some tools to the project root directory. To clean up after generating the coverage reports:

make coverage-clean

Building the documentation

To build the documentation:

This will build Node.js first (if necessary) and then use it to build the docs:

make doc

If you have an existing Node.js build, you can build just the docs with:

NODE=/path/to/node make doc-only

To read the man page:

man doc/node.1

If you prefer to read the full documentation in a browser, run the following.

make docserve

This will spin up a static file server and provide a URL to where you may browse the documentation locally.

If you're comfortable viewing the documentation using the program your operating system has associated with the default web browser, run the following.

make docopen

This will open a file URL to a one-page version of all the browsable HTML documents using the default browser.

make docclean

This will clean previously built doc.

To test if Node.js was built correctly:

./node -e "console.log('Hello from Node.js ' + process.version)"

Building a debug build

If you run into an issue where the information provided by the JS stack trace is not enough, or if you suspect the error happens outside of the JS VM, you can try to build a debug enabled binary:

./configure --debug
make -j4

make with ./configure --debug generates two binaries, the regular release one in out/Release/node and a debug binary in out/Debug/node, only the release version is actually installed when you run make install.

To use the debug build with all the normal dependencies overwrite the release version in the install directory:

make install PREFIX=/opt/node-debug/
cp -a -f out/Debug/node /opt/node-debug/node

When using the debug binary, core dumps will be generated in case of crashes. These core dumps are useful for debugging when provided with the corresponding original debug binary and system information.

Reading the core dump requires gdb built on the same platform the core dump was captured on (i.e. 64-bit gdb for node built on a 64-bit system, Linux gdb for node built on Linux) otherwise you will get errors like not in executable format: File format not recognized.

Example of generating a backtrace from the core dump:

$ gdb /opt/node-debug/node core.node.8.1535359906
(gdb) backtrace

Building an ASan build

ASan can help detect various memory related bugs. ASan builds are currently only supported on linux. If you want to check it on Windows or macOS or you want a consistent toolchain on Linux, you can try Docker (using an image like gengjiawen/node-build:2020-02-14).

The --debug is not necessary and will slow down build and testing, but it can show a clear stack trace if ASan hits an issue.

./configure --debug --enable-asan && make -j4
make test-only

Speeding up frequent rebuilds when developing

ccache

Tips: The ccache utility is widely used and should generally work fine. If you encounter any difficulties, consider disabling mold as a troubleshooting step.

If you plan to frequently rebuild Node.js, especially if using several branches, installing ccache can help to greatly reduce build times. Set up with:

On GNU/Linux:

Tips: mold can speed up the link process, which can't be cached, you may need to install the latest version but not the apt version.

sudo apt install ccache mold   # for Debian/Ubuntu, included in most Linux distros
export CC="ccache gcc"         # add to your .profile
export CXX="ccache g++"        # add to your .profile
export LDFLAGS="-fuse-ld=mold" # add to your .profile

Refs:

  1. https://ccache.dev/performance.html
  2. https://github.com/rui314/mold

On macOS:

brew install ccache            # see https://brew.sh
export CC="ccache cc"          # add to ~/.zshrc or other shell config file
export CXX="ccache c++"        # add to ~/.zshrc or other shell config file
Loading JS files from disk instead of embedding

When modifying only the JS layer in lib, it is possible to externally load it without modifying the executable:

./configure --node-builtin-modules-path "$(pwd)"

The resulting binary won't include any JS files and will try to load them from the specified directory. The JS debugger of Visual Studio Code supports this configuration since the November 2020 version and allows for setting breakpoints.

Troubleshooting Unix and macOS builds

Stale builds can sometimes result in file not found errors while building. This and some other problems can be resolved with make distclean. The distclean recipe aggressively removes build artifacts. You will need to build again (make -j4). Since all build artifacts have been removed, this rebuild may take a lot more time than previous builds. Additionally, distclean removes the file that stores the results of ./configure. If you ran ./configure with non-default options (such as --debug), you will need to run it again before invoking make -j4.

If you received the error nodejs g++ fatal error compilation terminated cc1plus during compilation, this is likely a memory issue and you should either provide more RAM or create swap space to accommodate toolchain requirements or reduce the number of parallel build tasks (-j<n>).

Windows

Tips

You may need to disable vcpkg integration if you encounter a link error about symbol redefinition related to zlib.lib(zlib1.dll), even if you never installed it by hand, as vcpkg is part of CLion and Visual Studio now.

# find your vcpkg
# double check vcpkg install the related file
vcpkg owns zlib.lib
vcpkg owns zlib1.dll
vcpkg integrate remove

Refs:

  1. #24448
  2. microsoft/vcpkg#37518 / microsoft/vcpkg#37546
  3. vcpkg

Windows Prerequisites

Option 1: Manual install
  • The current version of Python by following the instructions in Using Python on Windows.
  • Select and download the Visual Studio Community Edition 2026 from Visual Studio Downloads or alternatively download Build Tools for Visual Studio 2026, and then install. The Build Tools Edition has the lowest disk space requirements of all editions. Professional or Enterprise Editions can also be alternatively selected.
  • During installation of Visual Studio, select the "Desktop development with C++" workload. As of Node.js 24.0.0, ClangCL is required to compile on Windows. To install it, select the following two optional components:
    • C++ Clang Compiler for Windows (Microsoft.VisualStudio.Component.VC.Llvm.Clang)
    • MSBuild support for LLVM (clang-cl) toolset (Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset)
  • As an alternative to Visual Studio 2026, download Visual Studio 2022 Current channel Version 17.14 from the Evergreen bootstrappers table and install using the same workload and optional component selection as described above.
  • To install the Rust toolchain, required for Temporal support introduced in Node.js 26, ensure Visual Studio is already installed, then run rustup-init.exe downloaded from Install Rust, choosing the default: "Proceed with standard installation".
  • Basic Unix tools required for some tests, Git for Windows includes Git Bash and tools which can be included in the global PATH.
  • The NetWide Assembler, for OpenSSL assembler modules. If not installed in the default location, it needs to be manually added to PATH. A build with the openssl-no-asm option does not need this, nor does a build targeting ARM64 Windows.

After you have installed any Visual Studio Edition you can add optional components using the Modify / Individual Components tab of Visual Studio Installer.

Optional component required to build the MSI installer package:

  • The .NET SDK individual component (Microsoft.NetCore.Component.SDK)

Optional components required to compile for Windows on ARM64:

  • MSVC Build Tools for ARM64/ARM64EC (Microsoft.VisualStudio.Component.VC.Tools.ARM64)
  • C++ ATL for ARM64 (Microsoft.VisualStudio.Component.VC.ATL.ARM64)

NOTE: Currently we only support compiling with Clang that comes from Visual Studio.

When building with ClangCL, if the output from vcbuild.bat shows that the components are not installed, even when the Visual Studio Installer shows that they are installed, try removing the components first and then reinstalling them.

Option 2: Automated install with WinGet

WinGet configuration files can be used to install all the required prerequisites for Node.js development easily. These files will install the following WinGet packages:

  • Git for Windows with the git and Unix tools added to the PATH
  • Python 3.14
  • Visual Studio 2022 (Build Tools, Community, Professional or Enterprise Edition) and "Desktop development with C++" workload, Clang and ClangToolset optional components
  • Rust Toolchain MSVC