Overview Building Node.js from source allows you to contribute to the project, test changes, and customize your installation. The build process varies depending on your platform and specific requirements.
Node.js supports multiple platforms with different tiers of support:
Tier 1 : Full test coverage, test failures block releases (e.g., Linux x64/arm64, Windows x64, macOS)Tier 2 : Full test coverage but infrastructure issues may delay releases (e.g., Windows arm64, Linux ppc64le)Experimental : May not compile or pass all tests (e.g., FreeBSD, Android)
For production applications, run Node.js on supported platforms only. Node.js does not support End-of-Life (EoL) platforms.
Prerequisites General Requirements
Memory : At least 8GB of RAM for compiling with 4 parallel jobsPython : A supported version for building and testingDisk Space : Several GB for source code and build artifacts
Unix and macOS Unix Prerequisites # Ubuntu/Debian sudo apt-get install python3 g++-12 gcc-12 make python3-pip # Fedora sudo dnf install python3 gcc-c++ make python3-pip # CentOS/RHEL sudo yum install python3 gcc-c++ make python3-pip # Arch Linux sudo pacman -S python gcc make python-pip
macOS Prerequisites # Install Xcode Command Line Tools xcode-select --install
Requirements:
Xcode Command Line Tools >= 16.4
Python (supported version)
Windows Manual Installation
Python : Install from python.org Visual Studio : Download Visual Studio 2026 or 2022 with:
“Desktop development with C++” workload
C++ Clang Compiler for Windows
MSBuild support for LLVM (clang-cl) toolset
Git for Windows : Includes Git Bash and Unix toolsNetWide Assembler : Required for OpenSSL (except ARM64 builds)
Automated Installation with WinGet # Install all prerequisites automatically winget configure .\.configurations\configuration.dsc.yaml
Building on Unix/macOS Basic Build # Configure and build ./configure make -j4
The -j4 option runs 4 simultaneous compilation jobs to speed up the build.
If the path to your build directory contains a space, the build will likely fail.
Installing # Install to system directory [sudo] make install
Running Tests # Quick verification make test-only # Full test suite (before submitting PR) make -j4 test # Run specific test file tools/test.py test/parallel/test-stream2-transform.js # Run tests by subsystem tools/test.py child-process
Building Documentation # Build Node.js and documentation make doc # Build only documentation (with existing Node.js) NODE = /path/to/node make doc-only # Serve documentation locally make docserve # Open documentation in browser make docopen
Debug Build # Build with debug symbols ./configure --debug make -j4
This generates both release (out/Release/node) and debug (out/Debug/node) binaries.
Coverage Build # Build with coverage enabled ./configure --coverage make coverage # View coverage report # JavaScript: coverage/index.html # C++: coverage/cxxcoverage.html
Building on Windows Basic Build # Clone repository git clone https: // github.com / nodejs / node.git cd node # Build .\vcbuild # Run tests .\vcbuild test # Verify installation Release\node - e "console.log('Hello from Node.js', process.version)"
Enable symlinks by cloning with -c core.symlinks=true flag to avoid symlink-related issues.
Using ccache on Windows # Copy ccache executable cp c:\ccache\ ccache.exe c:\ccache\ cl.exe # Or for newer Visual Studio versions cp c:\ccache\ ccache.exe c:\ccache\ clang-cl.exe # Build with ccache .\ vcbuild.bat ccache c:\ccache\
Optimization Tips Using ccache (Unix/macOS) # Linux sudo apt install ccache mold export CC = "ccache gcc" export CXX = "ccache g++" export LDFLAGS = "-fuse-ld=mold" # macOS brew install ccache export CC = "ccache cc" export CXX = "ccache c++"
Loading JS Files from Disk When modifying only JavaScript files in lib/:
./configure --node-builtin-modules-path "$( pwd )"
This allows external loading without recompiling the executable.
Build Configurations ICU Support # Full ICU (all locales) - default ./configure --with-intl=full-icu # Small ICU (English only) ./configure --with-intl=small-icu # Without Intl support ./configure --without-intl # Use system ICU ./configure --with-intl=system-icu
OpenSSL Configuration # Configure OpenSSL appname ./configure --openssl-conf-name= < conf_name > # Build without assembler support ./configure --openssl-no-asm
ASan Build (Linux) # Address Sanitizer for memory bug detection ./configure --debug --enable-asan && make -j4 make test-only
Troubleshooting Stale Build Issues # Clean all build artifacts make distclean # Rebuild ./configure [your-options] make -j4
Memory Issues If you encounter compilation errors or “fatal error: compilation terminated”:
Add more RAM or create swap space
Reduce parallel build tasks: make -j2 or make -j1
Windows vcpkg Conflicts # Disable vcpkg integration if encountering zlib link errors vcpkg integrate remove
Android (Experimental) ./android-configure < path-to-ND K > < SDK-versio n > < architectur e > make -j4
Minimum Android SDK version: 24 (Android 7.0)
Supported architectures: arm, arm64, x86, x86_64
Nix Integration echo 'use_nix --arg sharedLibDeps {} --argstr icu small' > .envrc direnv allow . make build-ci -j12
Testing Your Build # Quick verification ./node -e "console.log('Hello from Node.js ' + process.version)" # Run test suite make test-only # Run with specific test pattern tools/test.py "test/parallel/test-stream-*"
Next Steps
Testing Guide Learn how to write and run tests
C++ Style Guide Follow C++ coding standards
Additional Resources 