Environment:Tensorflow Tfjs Node Native Runtime
| Metadata | |
|---|---|
| Source | TensorFlow.js |
| Domains | Infrastructure, Server_ML |
| Date | 2026-02-10 00:00 GMT |
Overview
Node.js runtime with native TensorFlow C library bindings for server-side ML (CPU and GPU).
Description
Server-side execution of TensorFlow.js via native C++ bindings to the TensorFlow library. The @tensorflow/tfjs-node package provides CPU support, while @tensorflow/tfjs-node-gpu adds CUDA-based GPU acceleration. Both packages use @mapbox/node-pre-gyp for pre-built binary distribution across platforms, eliminating the need to compile native bindings from source in most cases.
The native backend delivers significantly higher performance than the browser CPU backend for large models, making it suitable for production model training, batch inference, and model serving on servers.
Usage
Use for any server-side ML workflow — model training, batch inference, or serving. Much faster than the browser CPU backend for large models. This environment provides the same TensorFlow.js API as the browser version but executes operations through the native TensorFlow C library.
System Requirements
General
| Requirement | Details |
|---|---|
| Node.js | >= 8.11.0 (from engines field in package.json)
|
| N-API | Versions 3–9 supported (from binary field) |
CPU Support
| Platform | Minimum Version |
|---|---|
| Linux | Ubuntu 14.04+ |
| macOS | 10.12.6+ (Sierra) |
| Windows | Windows 7+ |
| macOS M1 (arm64) | arm64 build only (Rosetta must be off) |
| Raspberry Pi | Requires rebuild from source |
GPU Support (CUDA)
| Requirement | Details |
|---|---|
| Platforms | Linux or Windows only (no macOS GPU support) |
| NVIDIA GPU Drivers | > 450.x |
| CUDA Toolkit | 11.2 |
| cuDNN SDK | 8.1.0 |
Platform-Specific Notes
- macOS: Xcode command line tools required for native compilation.
- macOS M1: Must use arm64 Node.js build (Rosetta must be disabled).
- Windows: Requires
node-gypand a supported Python version. - Raspberry Pi: Requires rebuild from source:
npm rebuild @tensorflow/tfjs-node --build-from-source
Dependencies
CPU Package
npm install @tensorflow/tfjs-node
GPU Package
npm install @tensorflow/tfjs-node-gpu
Internal Dependencies
| Package | Version | Purpose |
|---|---|---|
@mapbox/node-pre-gyp |
1.0.9 | Pre-built native binary distribution |
adm-zip |
— | ZIP archive extraction for binary packages |
google-protobuf |
— | Protocol buffer serialization |
https-proxy-agent |
— | HTTP proxy support for binary downloads |
progress |
— | Download progress display |
rimraf |
— | Cross-platform file removal |
tar |
— | Tarball extraction for binary packages |
Credentials
No credentials are required for basic usage. The following optional environment variables control binary download behavior:
| Variable | Purpose |
|---|---|
TFJS_NODE_CDN_STORAGE |
Custom CDN endpoint for pre-built binary downloads |
TFJS_NODE_BASE_URI |
Custom base URI for TensorFlow C library mirror |
Quick Install
CPU
npm install @tensorflow/tfjs-node
GPU (CUDA)
npm install @tensorflow/tfjs-node-gpu
Code Evidence
Node.js Engine Requirement
From tfjs-node/package.json:13-15:
"engines": {
"node": ">=8.11.0"
}
N-API versions 3–9 are supported in the binary field, ensuring compatibility across a wide range of Node.js releases.
Common Errors
| Error | Cause | Solution |
|---|---|---|
| The system cannot find the path specified (Windows) | Native binary path resolution failure | Run node-gyp configure --verbose to diagnose path issues.
|
| msbuild.exe failures (Windows) | Missing C++ build tools | Install windows-build-tools via: npm install --global windows-build-tools
|
| Missing python2 | Python not found during native compilation | Install Python via: npm install --global --add-python-to-path install windows-build-tools
|
| Rebuild required on Raspberry Pi | No pre-built binary for ARM architecture | Run npm rebuild @tensorflow/tfjs-node --build-from-source
|
Compatibility Notes
- GPU support is available only on Linux and Windows. macOS does not support CUDA acceleration.
- Mac M1 (Apple Silicon) requires an arm64 build of Node.js. Rosetta translation mode is not supported.
- Raspberry Pi and other ARM devices require rebuilding the native bindings from source.
- Pre-built binaries are distributed via
@mapbox/node-pre-gyp, so most users do not need a C++ compiler. Source compilation is only needed for unsupported platforms. - GPU and CPU packages are mutually exclusive — install only one of
@tensorflow/tfjs-nodeor@tensorflow/tfjs-node-gpu.