{"id":1582,"library":"nodejs-wheel-binaries","title":"Node.js Wheel Binaries","description":"The `nodejs-wheel-binaries` library provides unofficial Node.js and npm binaries packaged as a Python wheel. This allows Python projects to easily access and execute Node.js without requiring a system-wide Node.js installation, particularly useful in isolated or CI/CD environments. The current version is 24.14.1, and it typically releases new versions corresponding to major Node.js updates.","status":"active","version":"24.14.1","language":"en","source_language":"en","source_url":"https://github.com/nodejs-wheel-binaries/nodejs-wheel-binaries","tags":["nodejs","binaries","npm","javascript","tooling","subprocess"],"install":[{"cmd":"pip install nodejs-wheel-binaries","lang":"bash","label":"Install Node.js Wheel"}],"dependencies":[],"imports":[{"note":"This library provides the path to Node.js binaries, not a Python API for Node.js. It does not provide 'nodejs' as a Python module.","wrong":"import nodejs","symbol":"find_nodejs_bin","correct":"from nodejs_wheel_binaries import find_nodejs_bin"},{"note":"Use this to locate the npm executable provided by the wheel.","symbol":"find_npm_bin","correct":"from nodejs_wheel_binaries import find_npm_bin"}],"quickstart":{"code":"import subprocess\nfrom nodejs_wheel_binaries import find_nodejs_bin, find_npm_bin\n\n# Find the Node.js executable\nnode_bin = find_nodejs_bin()\nnpm_bin = find_npm_bin()\n\nif node_bin:\n    print(f\"Node.js binary found at: {node_bin}\")\n    try:\n        # Run a simple Node.js command to get its version\n        result = subprocess.run([node_bin, '--version'], capture_output=True, text=True, check=True)\n        print(f\"Node.js version: {result.stdout.strip()}\")\n\n        # Example: Run a simple JS script directly\n        js_code = \"console.log('Hello from Node.js via Python!');\"\n        result = subprocess.run([node_bin, '-e', js_code], capture_output=True, text=True, check=True)\n        print(f\"Node.js script output: {result.stdout.strip()}\")\n\n    except FileNotFoundError:\n        print(\"Node.js executable not found in PATH after discovery.\")\n    except subprocess.CalledProcessError as e:\n        print(f\"Error running Node.js command: {e}\")\n        print(f\"Stderr: {e.stderr}\")\nelse:\n    print(\"Node.js binary could not be found by the wheel.\")\n\nif npm_bin:\n    print(f\"\\nNPM binary found at: {npm_bin}\")\n    try:\n        # Run a simple NPM command to get its version\n        result = subprocess.run([npm_bin, '--version'], capture_output=True, text=True, check=True)\n        print(f\"NPM version: {result.stdout.strip()}\")\n    except subprocess.CalledProcessError as e:\n        print(f\"Error running NPM command: {e}\")\n        print(f\"Stderr: {e.stderr}\")","lang":"python","description":"This quickstart demonstrates how to locate the Node.js and npm executables provided by the package and then execute simple commands using `subprocess`. This is the primary way to interact with Node.js via this library."},"warnings":[{"fix":"Always use `find_nodejs_bin()` or `find_npm_bin()` to get the executable path, then execute it via `subprocess.run()`.","message":"This library provides Node.js and npm binaries for execution, not a Python wrapper or API. You cannot `import nodejs` and call Python functions; you must use `subprocess` to run the discovered binaries (`node_bin`, `npm_bin`).","severity":"gotcha","affected_versions":"All"},{"fix":"Always retrieve binary paths using `from nodejs_wheel_binaries import find_nodejs_bin, find_npm_bin` and pass these paths to `subprocess` calls.","message":"The package does not automatically add `node` or `npm` to your system's PATH. You must explicitly import and use `find_nodejs_bin()` and `find_npm_bin()` to locate the executables within the Python environment.","severity":"gotcha","affected_versions":"All"},{"fix":"Install additional Node.js tools via `npm install -g <tool-name>` using the `npm_bin` provided by `nodejs-wheel-binaries`.","message":"Other Node.js ecosystem tools like `npx` or `yarn` are not directly provided by this wheel. If needed, you must install them globally using the `npm_bin` found by this package (e.g., `subprocess.run([npm_bin, 'install', '-g', 'npx'])`).","severity":"gotcha","affected_versions":"All"},{"fix":"When upgrading `nodejs-wheel-binaries` to a version that bundles a new major Node.js release, thoroughly test your Node.js scripts for compatibility with the new Node.js version. Consult Node.js release notes for breaking changes.","message":"While the Python library aims for stability, the included Node.js binary itself is subject to Node.js's release cycle. Changes in Node.js behavior, deprecations, or API shifts (e.g., in module resolution, core APIs) can break your Node.js code, even if the Python library still correctly provides the binary. This is especially relevant when updating to new major Node.js versions (e.g., v18 to v20, v20 to v22).","severity":"breaking","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}