Unofficial Node.js Wheel

24.14.1 · active · verified Wed Apr 15

nodejs-wheel is an unofficial Python package that distributes prebuilt Node.js binaries as wheels on PyPI. It enables Python projects to declare and install Node.js as a dependency via `pip`, providing access to `node`, `npm`, and `npx` commands within a Python environment. The current version, 24.14.1, was released on March 31, 2026, and the project generally follows the Node.js release schedule, which sees new major versions biannually in April and October. It supports Python 3.7 and above.

Warnings

gotcha This is an unofficial distribution of Node.js. While it aims to provide official binaries, users should be aware that it's not maintained by the official Node.js project.
Fix: Verify the source and integrity if strict official guarantees are required. For production environments, consider official Node.js installation methods if this unofficial distribution poses a concern.
breaking Upgrading major versions of `nodejs-wheel` (which correspond to Node.js major versions) may introduce breaking changes from Node.js itself, including changes to platform support (e.g., macOS minimum versions, 32-bit OS deprecation), OpenSSL versions, and core API behaviors. For example, Node.js v24 deprecated 32-bit Windows and armv7 Linux binaries, and requires macOS 13.5+ for pre-built binaries.
Fix: Refer to the official Node.js release notes for breaking changes and test thoroughly before upgrading. Ensure your environment meets the minimum requirements for the target Node.js version.
gotcha For installations where only the Node.js binaries are needed and Python API/CLI integration is not desired, consider installing `nodejs-wheel-binaries` directly. This avoids installing the full `nodejs-wheel` package, which acts as a wrapper and adds CLI entry points.
Fix: Use `pip install nodejs-wheel-binaries` if only binaries are required. If both `nodejs-wheel` and `nodejs-wheel-binaries` are installed, `nodejs-wheel`'s entry points will take precedence.
gotcha When using the Python API (e.g., `node()`, `npm()`), the functions by default return the exit code (an `int`). To get a `subprocess.CompletedProcess` object for richer output, error stream, and process handling, pass `return_completed_process=True` to the function call.
Fix: Modify API calls to `function_name(..., return_completed_process=True)` to receive the `CompletedProcess` object.
gotcha Node.js applications, whether executed via this package or directly, can be prone to common issues like blocking the event loop with synchronous operations, unhandled asynchronous errors (Promise rejections), and module not found errors.
Fix: Adhere to Node.js best practices for asynchronous programming, error handling (e.g., `try-catch` with `async/await`, `.catch()` for Promises), and proper module resolution. Utilize Node.js-specific debugging tools when developing and testing Node.js code.

Install

pip install nodejs-wheel Full package with CLI and Python API
pip install nodejs-wheel-binaries Binaries only (no Python API/CLI wrapper)

Imports

node
```
from nodejs_wheel import node
```
npm
```
from nodejs_wheel import npm
```
npx
```
from nodejs_wheel import npx
```
corepack
```
from nodejs_wheel import corepack
```
Available since v22.13.1.

Quickstart

This quickstart demonstrates how to import and execute Node.js and npm commands directly from Python. It shows how to retrieve both the exit code and the full `subprocess.CompletedProcess` object for more detailed output handling.

import os
from nodejs_wheel import node, npm

# Run a Node.js command and get the exit code
node_version_exit_code = node(['--version'])
print(f'Node.js --version exit code: {node_version_exit_code}')

# Run a Node.js command and get the CompletedProcess object for detailed output
node_version_process = node(['--version'], return_completed_process=True)
print(f'Node.js version: {node_version_process.stdout.strip()}')

# Run an npm command
npm_version_process = npm(['--version'], return_completed_process=True)
print(f'npm version: {npm_version_process.stdout.strip()}')

view raw JSON →