Skip to main content

​
Overview

Building Node.js from source gives you full control over the build configuration and allows you to customize the runtime for your specific needs. This guide covers building Node.js on all supported platforms.
For production applications, run Node.js on supported platforms only. See the supported platforms section for details.

​
Supported Platforms

Node.js supports three support tiers:
  • Tier 1: Majority of Node.js users. Full test coverage maintained. Test failures block releases.
  • Tier 2: Smaller user segments. Full test coverage maintained. Test failures block releases.
  • Experimental: May not compile or pass tests. No official releases.

​
Platform List

Operating SystemArchitecturesVersionsSupport Type
GNU/Linuxx64kernel >= 4.18, glibc >= 2.28Tier 1
GNU/Linuxarm64kernel >= 4.18, glibc >= 2.28Tier 1
Windowsx64>= Windows 10/Server 2016Tier 1
macOSx64, arm64>= 13.5Tier 1
GNU/Linuxppc64le (>=power9)kernel >= 4.18, glibc >= 2.28Tier 2
GNU/Linuxs390x (>=z14)kernel >= 4.18, glibc >= 2.28Tier 2

​
Supported Toolchains

Operating SystemCompiler Versions
LinuxGCC >= 12.2 or Clang >= 19.1
WindowsVisual Studio 2022 or 2026 with Windows 10 or 11 SDK
macOSXcode >= 16.4 (Apple LLVM >= 19)

​
Prerequisites

Building Node.js requires at least 8GB of RAM when compiling with 4 parallel jobs.

​
All Platforms

  • A supported version of Python (for building and testing)
  • At least 8GB of RAM for compilation

​
Building on Unix and macOS

​
Unix Prerequisites

Install the required dependencies: 
sudo apt-get install python3 g++-12 gcc-12 make python3-pip

​
macOS Prerequisites

Install Xcode Command Line Tools: 
xcode-select --install
Alternatively, install the full Xcode from the Mac App Store, then find the Command Line Tools under Xcode -> Open Developer Tool -> More Developer Tools...

​
Building Node.js

1

Clone the repository

git clone https://github.com/nodejs/node.git
cd node
2

Configure the build

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

Compile Node.js

make -j4
The -j4 option runs 4 simultaneous compilation jobs to speed up the build.
4

Verify the build

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

​
Installing Node.js

To install the built version to a system directory: 
[sudo] make install

​
Running Tests

Verify the build works correctly: 
make test-only
For a full check before submitting a pull request: 
make -j4 test
To run a single test file: 
tools/test.py test/parallel/test-stream2-transform.js

​
Building on Windows

​
Windows Prerequisites

  1. Install the current version of Python from python.org
  2. Download Visual Studio Community Edition 2026 or Build Tools for Visual Studio 2026
  3. During installation, select “Desktop development with C++” workload
  4. Install these optional components:
    • C++ Clang Compiler for Windows
    • MSBuild support for LLVM (clang-cl) toolset
  5. Install Git for Windows (includes Git Bash and Unix tools)
  6. Install NetWide Assembler (NASM) for OpenSSL assembler modules

​
Building Node.js on Windows

1

Clone the repository

git clone https://github.com/nodejs/node.git
cd node
Enable symlinks by cloning with: git clone -c core.symlinks=true <repository_url>
2

Build Node.js

.\vcbuild
3

Run tests

.\vcbuild test
4

Verify the build

Release\node -e "console.log('Hello from Node.js', process.version)"

​
Build Configuration Options

​
Debug Build

Create a debug build for detailed error information: 
./configure --debug
make -j4
This generates two binaries:
  • out/Release/node - Release version
  • out/Debug/node - Debug version with symbols

​
ICU (Internationalization) Support

./configure --with-intl=full-icu
All locales supported by ICU.

​
Building with ccache

Speed up rebuilds by using ccache: 
sudo apt install ccache mold
export CC="ccache gcc"
export CXX="ccache g++"
export LDFLAGS="-fuse-ld=mold"

​
Troubleshooting

​
Stale Builds

If you encounter “file not found” errors: 
make distclean
./configure  # Re-run with your original options
make -j4
distclean removes all build artifacts and configuration. You’ll need to reconfigure before building.

​
Memory Issues

If you receive compilation errors like g++ fatal error compilation terminated:
  • Provide more RAM
  • Create swap space
  • Reduce parallel build tasks: make -j2 instead of make -j4

​
Path with Spaces

Avoid build directories with spaces or non-ASCII characters in the path. This will likely cause the build to fail.

​
Advanced Options

​
ASan Build

Build with Address Sanitizer to detect memory bugs: 
./configure --debug --enable-asan
make -j4
make test-only

​
Loading JS Files from Disk

For faster development, load JS files externally instead of embedding: 
./configure --node-builtin-modules-path "$(pwd)"

​
Building with Ninja

For faster builds, use Ninja instead of Make. See the Building Node.js with Ninja guide.

​
Next Steps

Testing

Learn how to run and write tests

Debugging

Debug your Node.js build

Performance

Profile and optimize your code

Security

Security best practices