process.arch
Reports the CPU architecture the running Node.js binary was compiled for, such as 'x64' or 'arm64'.
process.arch- Added in Node.js v0.5.0
Return value
stringOne of 'arm', 'arm64', 'ia32', 'loong64', 'mips', 'mipsel', 'ppc64', 'riscv64', 's390', 's390x' or 'x64'.
process.arch names the CPU architecture the Node binary itself was built for. The documented values are 'arm', 'arm64', 'ia32', 'loong64', 'mips', 'mipsel', 'ppc64', 'riscv64', 's390', 's390x' and 'x64'.
When to reach for it
Almost always in combination with process.platform: the pair ${platform}-${arch} is the conventional key for prebuilt native addons, downloaded release assets and Docker image tags. It is also the first thing to print when a compiled dependency fails to load.
What trips people up
- It describes the build, not the hardware. An x64 Node running under Rosetta 2 on an Apple Silicon Mac reports
'x64', and a 32-bit Node on 64-bit Windows reports'ia32'. If you install native modules for that value you get the right ones — which is the point — but it is not a hardware probe. Useos.cpus()oros.machine()when you genuinely need the physical CPU. - Mixed architectures break addons. Copying a
node_modulesdirectory from an x64 machine to an arm64 one produces an invalid ELF header or a missing.nodebinding; the fix is rebuilding, not retrying.
os.arch() returns the identical string.
Example
When to use it
- Build the download name for a prebuilt native binary, such as sharp-linux-arm64.tar.gz.
- Print platform and architecture in a diagnostics dump when a native addon fails to load.
- Select the correct Docker base image tag in a release script.
- Detect that a 32-bit build is limiting the usable heap on a 64-bit machine.
Frequently asked questions
How do I tell if Node.js is a 64-bit build?
Check whether process.arch is one of 'x64', 'arm64', 'ppc64', 's390x', 'riscv64' or 'loong64'; 'ia32', 'arm', 'mips', 'mipsel' and 's390' are 32-bit. This matters because a 32-bit build caps the V8 heap at roughly 1 GB regardless of installed RAM.
Why does process.arch say x64 on my M1 or M2 Mac?
Because the Node binary you installed is an x64 build running under Rosetta 2, and process.arch reports the architecture Node was compiled for. Reinstall the arm64 build for native speed, and check os.cpus()[0].model if you need to see the real chip.
What is the difference between process.arch and os.arch()?
They return the same string; os.arch() just requires importing the os module. Both describe the Node build target rather than the physical processor.
More examples
Choosing a prebuilt binary
The output shows the two paths through the same code. The failure message is the valuable half: it names the target that was looked for and lists what actually shipped, which turns an opaque `MODULE_NOT_FOUND` into a report you can act on. Sorting the directory listing keeps the message stable rather than dependent on filesystem ordering.
const fs = require('node:fs');
const path = require('node:path');
const target = `${process.platform}-${process.arch}`;
const candidate = path.join(__dirname, 'prebuilds', target, 'engine.node');
if (!fs.existsSync(candidate)) {
throw new Error(
`No prebuilt binary for ${target}. ` +
`Available: ${fs.readdirSync(path.join(__dirname, 'prebuilds')).sort().join(', ')}`
);
}
const engine = require(candidate);
console.log('loaded:', target);
// loaded: darwin-arm64
// or, on an unsupported host:
// Error: No prebuilt binary for linux-riscv64. Available: darwin-arm64, darwin-x64, linux-x64, win32-x64Build versus hardware architecture
The output shows the mismatch that catches people out: both `process.arch` and `os.arch()` report `x64` because they describe the Node binary, while the CPU model reveals an Apple Silicon chip running it through translation. Installing an arm64 build here typically doubles throughput, and native modules compiled on the arm64 build will refuse to load on the x64 one.
const os = require('node:os');
console.log('node build target:', `${process.platform}-${process.arch}`);
console.log('os.arch() :', os.arch());
console.log('cpu model :', os.cpus()[0].model);
if (process.platform === 'darwin' && process.arch === 'x64' && os.cpus()[0].model.includes('Apple')) {
console.log('warning: x64 Node running under Rosetta on Apple Silicon');
}
// node build target: darwin-x64
// os.arch() : x64
// cpu model : Apple M2 Pro
// warning: x64 Node running under Rosetta on Apple Silicon
Discussion