{"id":6741,"library":"nodejs-wheel","title":"Unofficial Node.js Wheel","description":"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.","status":"active","version":"24.14.1","language":"en","source_language":"en","source_url":"https://github.com/njzjz/nodejs-wheel","tags":["Node.js","JavaScript runtime","binary wheel","CLI","npm","npx"],"install":[{"cmd":"pip install nodejs-wheel","lang":"bash","label":"Full package with CLI and Python API"},{"cmd":"pip install nodejs-wheel-binaries","lang":"bash","label":"Binaries only (no Python API/CLI wrapper)"}],"dependencies":[{"reason":"Direct dependency for core binaries; can be installed separately for minimal footprint.","package":"nodejs-wheel-binaries","optional":true}],"imports":[{"symbol":"node","correct":"from nodejs_wheel import node"},{"symbol":"npm","correct":"from nodejs_wheel import npm"},{"symbol":"npx","correct":"from nodejs_wheel import npx"},{"note":"Available since v22.13.1.","symbol":"corepack","correct":"from nodejs_wheel import corepack"}],"quickstart":{"code":"import os\nfrom nodejs_wheel import node, npm\n\n# Run a Node.js command and get the exit code\nnode_version_exit_code = node(['--version'])\nprint(f'Node.js --version exit code: {node_version_exit_code}')\n\n# Run a Node.js command and get the CompletedProcess object for detailed output\nnode_version_process = node(['--version'], return_completed_process=True)\nprint(f'Node.js version: {node_version_process.stdout.strip()}')\n\n# Run an npm command\nnpm_version_process = npm(['--version'], return_completed_process=True)\nprint(f'npm version: {npm_version_process.stdout.strip()}')\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All major version upgrades (e.g., v22 to v24)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions >= 20.13.0"},{"fix":"Modify API calls to `function_name(..., return_completed_process=True)` to receive the `CompletedProcess` object.","message":"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.","severity":"gotcha","affected_versions":"All versions >= 20.13.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}