Registry / ai-ml / node-calls-python

node-calls-python

library1.11.1jsnpmunverified

Node.js addon that embeds Python using N-API and Python C API, allowing direct in-process execution of Python code without spawning child processes. Version 1.11.1 ships TypeScript types and supports Python 3.x. Unlike child_process or socket-based approaches, it keeps data in shared memory and avoids IPC overhead, making it suitable for rapid ML/DL model inference or small NumPy operations. Release cadence is moderate; requires node-gyp for native compilation. Better than python-shell for latency-sensitive scenarios but limited to Python 3 and may need platform-specific build setup.

ai-ml

npm install node-calls-python

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-CALLS-PYTHON

node-calls-python

ai-mljavascriptv1.11.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

interpreter

✓ import { interpreter } from 'node-calls-python'

✗ const nodecallspython = require('node-calls-python'); const py = nodecallspython.interpreter

ESM import since v1.11.0; CommonJS still works but prefer ESM for type safety.

PythonInterpreter

✓ import { PythonInterpreter } from 'node-calls-python'

✗ const { PythonInterpreter } = require('node-calls-python')

Only exported as named type; cannot instantiate directly. Use interpreter singleton.

Interpreter (type)

✓ import type { Interpreter } from 'node-calls-python'

TypeScript users should import the Interpreter type to type-check callbacks or custom wrappers.

Shows async/sync calling, class instantiation, and memory management with node-calls-python.

import { interpreter } from 'node-calls-python'; async function main() { // Import a Python module const pymodule = await interpreter.import('test'); // assumes test.py in cwd // Call a Python function asynchronously const result = await interpreter.call(pymodule, 'add', 3, 4); console.log('add result:', result); // 7 // Create a Python object const calc = await interpreter.create(pymodule, 'Calculator', [5, 6, 7]); // Call a method on the object synchronously const sum = interpreter.callSync(calc, 'sum_vector'); console.log('vector sum:', sum); // 18 // Destroy object to free memory await interpreter.destroy(calc); } main().catch(console.error);

Debug

Known issues

gotchaNative build requires Python 3.x headers and node-gyp; missing python3-dev on Linux or windows-build-tools on Windows causes installation failure.

fix

Install python3-dev (Linux), windows-build-tools (Windows), or Xcode (macOS). See README FAQ.

affects: >=1.0.0

breakingVersion 1.11.0 switched to ESM-first exports. Dynamic require() may fail in pure ESM projects or when `type: module` is set in package.json.

fix

Use import { interpreter } from 'node-calls-python' or set package.json type to commonjs.

affects: >=1.11.0

gotchaPython objects must be cleaned up with interpreter.destroy() to prevent memory leaks; failure to do so may cause gradual memory growth in long-running processes.

fix

Always call await interpreter.destroy(pyObject) when finished, or use a try/finally pattern.

affects: >=1.0.0

gotchaOnly Python 3 is supported; Python 2 usage will fail during build.

fix

Ensure python3 points to Python 3.x and python3-dev is installed.

affects: >=1.0.0

gotchaOn ARM macOS (M1/M2), default npm install may fail because of architecture mismatch in native addon.

fix

npm install --arch=arm64 --target_arch=arm64 node-calls-python

affects: >=1.0.0

Errors

Common errors & fixes

gyp ERR! stack Error: not found: make

Missing build-essential on Linux (no make/g++).

fix

sudo apt install make g++

Module not found: Can't resolve 'node-calls-python'

ESM import used but package not installed or node_modules missing.

fix

npm install node-calls-python

TypeError: interpreter.call is not a function

Using older CommonJS syntax without accessing .interpreter property correctly.

fix

const py = require('node-calls-python').interpreter; // or use ESM import

ImportError: No module named 'numpy'

Python environment lacks numpy but Python code depends on it.

fix

pip install numpy (or install in the same Python environment that node-gyp links to)

Upgrade

Version history

1.11.1latest on npm

Audit

Dependencies

node-gyprequiredNative addon requires compilation of C++ code against Python and Node headers.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/hmenyus/node-calls-python ↗

packagenode-calls-python ↗

homepagehttps://github.com/hmenyus/node-calls-python#readme ↗