How to Build Node.js from Source

Building Node.js from source is a great way to understand its internals or customize it for your needs. This guide walks you through the process step by step, keeping it simple and focused for Linux users.

About Me and This Guide

Hi, I’m Jesús Paz, a maintainer of the NodeSource Distributions repository. For over 5 years, I’ve been focused on building Node.js binaries and creating Debian and RPM packages that make installing Node.js as simple as running apt or dnf. The NodeSource Distributions project, active for nearly a decade, ensures developers can install and manage Node.js effortlessly, letting the package manager handle complexities.

This guide offers a quick, practical reference for building Node.js from source—perfect for beginners or those needing a refresher. Plus, it’s a handy way for me to document and share lessons from years of experience.

What You’ll Need

To build Node.js, ensure you have the following:

  1. GCC and G++: Version 12.2 or newer.
  2. GNU Make: Version 3.81 or newer.
  3. Python: Version 3.x (required for the build process).
  4. glibc (GNU C Library): Ensure you have version 2.28 or newer to avoid compatibility issues.

What is glibc?

glibc is a core part of Linux that provides fundamental system libraries. Node.js relies on it during the build. If you’re using an older Linux distribution, you may encounter issues due to an outdated glibc version, particularly between versions 2.16 and 2.18. These versions had compatibility problems with Node.js builds. For Node.js versions 18 and above, glibc 2.28 or newer is required.

If your system doesn’t meet this requirement, refer to the Unofficial Builds Repository for a detailed guide on how to work around glibc version limitations.

Step-by-Step Guide

1. Choose a Branch

Before starting, decide which version of Node.js you want to build. Each version corresponds to a specific branch in the Node.js repository. For example:

  • Version 18: v18.x
  • Version 20: v20.x
  • Version 22: v22.x
  • Latest development version: main

For this guide, we’ll use the main branch. To build a specific version, checkout the corresponding branch:

git checkout v20.x

2. Install Dependencies

Run the following command to install the required tools and libraries:

sudo apt update
sudo apt install -y python3 g++-12 gcc-12 make python3-pip

If you're using a different package manager (e.g., dnf for Fedora), replace apt with your system's package manager.

3. Clone the Node.js Repository

Clone the Node.js source code from its official GitHub repository:

git clone https://github.com/nodejs/node.git
cd node
git checkout main  # Or the branch you chose in Step 1

4. Configure the Build

Set up the build configuration using the configure script. This ensures the build system is prepared for your environment:

export CXX=g++-12
./configure

Tip: If you encounter errors related to glibc, verify your system version with ldd --version. Consider upgrading your Linux distribution or using a container with a newer glibc version.

5. Compile Node.js

Run the following command to compile Node.js:

make -j$(nproc)
  • make starts the compilation process.
  • -j$(nproc) uses all available CPU cores to speed up the build.

6. Verify the Build

After the build is complete, test the Node.js binary:

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

You should see a message displaying the Node.js version you just built.

7. Install Node.js (Optional)

To make your custom-built Node.js available system-wide, install it:

sudo make install

Additional Notes

  1. glibc Compatibility:

    • Node.js versions 18 and above require glibc 2.28 or newer.
    • If you encounter compatibility issues, refer to the Unofficial Builds Repository for guidance.

  2. Branch-Specific Information:

    • The build process and requirements may vary depending on the branch you’re using.
    • Refer to the official BUILDING.md documentation for the most accurate and up-to-date information.

  3. Future Blog Post:

    • A future post will provide a more detailed guide on working with older glibc versions and their impact on Node.js builds.

Why Build Node.js?

Building Node.js from source allows you to:

  • Customize the binary for specific needs.
  • Test or contribute to the latest features.
  • Learn more about its internals.

With this guide, you now have the tools to build Node.js on Linux confidently. Happy coding!