NodPy 🐍⚡

Hybrid Node.js × Python runtime — Write JavaScript/Node syntax, run Python inline. One language, two ecosystems.

// app.nodpy
import express from 'express'
import py "statistics" as stats
import py "json"

const app = express()
app.use(express.json())

app.post('/api/analyze', async (req, res) => {
  const { data } = req.body
  $data   // bridge JS variable to Python

  const result = await python {
    __nodpy_result__ = {
      "mean":   round(statistics.mean(data), 2),
      "median": round(statistics.median(data), 2),
      "stdev":  round(statistics.stdev(data), 2),
    }
  }
  res.json(result)
})

app.listen(3000, () => console.log('http://localhost:3000'))

Install

npm install -g muk-nodpy

One-line (macOS/Linux):

curl -fsSL https://raw.githubusercontent.com/muktiaji13/nodpy/main/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/muktiaji13/nodpy/main/install.ps1 | iex

From source:

git clone https://github.com/muktiaji13/nodpy.git
cd nodpy
npm install -g .

Quick start

# Create a project from a template
nodpy new myapp --template=express
cd myapp
nodpy install-node express     # install Node packages
nodpy run main.nodpy           # run it
# → http://localhost:3000

Templates

| Template | Command | What it creates | |----------|---------|-----------------| | basic | nodpy new myapp | Minimal starter | | express | nodpy new myapp --template=express | Express server + public/ HTML frontend + Python backend | | api | nodpy new myapp --template=api | REST API with Express + Python data processing | | game | nodpy new myapp --template=game | Game server with Python game logic + browser UI |

Project structure

myapp/
├── main.nodpy          ← entry point
├── nodpy.json          ← project config (Python + Node deps)
├── .env                ← environment variables (auto-loaded)
├── public/             ← static files served by Express
│   ├── index.html
│   ├── style.css
│   └── app.js
└── node_modules/       ← Node packages (npm install)

nodpy.json

{
  "name": "myapp",
  "version": "1.0.0",
  "main": "main.nodpy",
  "python": {
    "packages": ["numpy", "pandas", "requests"]
  },
  "node": {
    "packages": ["express", "cors"]
  }
}

Both python.packages and node.packages are auto-installed when missing on the first run.

Language syntax

Import Python modules

import py "numpy" as np
import py "pandas" as pd
import py "os.path" as osp

Call Python (all async)

const mean  = await np.mean([1, 2, 3, 4, 5])
const norm  = await np.linalg.norm([3, 4])   // chained attributes
const pi    = await np.pi                     // attribute access

Python blocks

python {
  for i in range(5):
      print(f"step {i}")
}

Capture return value from Python

const primes = await python {
  def sieve(n):
      is_prime = [True] * (n+1)
      is_prime[0] = is_prime[1] = False
      for i in range(2, int(n**0.5)+1):
          if is_prime[i]:
              for j in range(i*i, n+1, i): is_prime[j] = False
      return [i for i in range(n+1) if is_prime[i]]
  __nodpy_result__ = sieve(100)
}
console.log(primes.filter(p => p > 50))

Bridge JS → Python

$varName shorthand:

const data = [1, 2, 3, 4, 5]
$data                             // sends data to Python
python { print(sum(data)) }       // → 15

Manual:

await __nodpy.pyset({ x: 42, matrix: [[1,2],[3,4]] })

Inline Python eval

const tau   = py`math.pi * 2`
const upper = py`"hello".upper()`

Environment variables

.env is auto-loaded. Available in both Node.js and Python:

# .env
APP_PORT=3000
DB_URL=sqlite:///data.db
SECRET_KEY=abc123

// In .nodpy file
const port = process.env.APP_PORT   // Node.js

python {
  import os
  port = os.environ["APP_PORT"]     // Python sees the same values
}

Regular Node.js (unchanged)

import fs from 'fs'
import { createHash } from 'crypto'
import express from 'express'

Package management

# Python packages (pip)
nodpy install numpy pandas scikit-learn
nodpy install requests --upgrade

# Node.js packages (npm) — installs in project root
nodpy install-node express cors helmet
nodpy install-node jest --save-dev

Both commands automatically update nodpy.json.

Important: Always run nodpy install-node from your project root (where nodpy.json is), or from any subdirectory — it detects the project root automatically.

Web apps with Express

Structure your project like this:

myapp/
├── main.nodpy       ← Express server + Python routes
├── public/
│   ├── index.html   ← Frontend HTML
│   ├── style.css
│   └── app.js       ← Frontend JS (fetch() calls to your API)
└── nodpy.json

In main.nodpy:

import express from 'express'

const app = express()
app.use(express.json())
app.use(express.static('public'))   // serves public/ folder

app.get('/api/hello', (req, res) => res.json({ msg: 'Hello!' }))

app.listen(3000)

The public/ folder is served statically — http://localhost:3000 → public/index.html.

REPL

nodpy repl

NodPy REPL  v0.3.0  ·  Node v22.0.0  ·  Python 3.12.3

nopy> import py "math"
nopy> const x = await math.sqrt(144)
nopy> console.log("sqrt(144) =", x)
sqrt(144) = 12
nopy> $x
nopy> python { print("Python sees x:", x) }
Python sees x: 12
nopy> .exit

REPL commands: .help, .clear, .reset, .tape, .doctor, .py <expr>, .exit

Commands

nodpy new <n> [--template=T]        Create project from template
nodpy run <file.nodpy>              Run a script
nodpy run <file.nodpy> --watch      Run + auto-reload on save
nodpy repl                          Interactive shell
nodpy init [name]                   Scaffold basic project
nodpy install <pkg> [...]           Install Python packages (pip)
nodpy install-node <pkg> [...]      Install Node.js packages (npm)
nodpy version                       Show installed + latest
nodpy upgrade                       Update NodPy to latest
nodpy doctor                        Check environment health
nodpy install-python                Auto-download portable Python
nodpy vscode                        Install VS Code extension
nodpy config get/set <key> [val]    Read/write config
nodpy check <file.nodpy>            Preview transformed JS (debug)
nodpy help                          Full help

Requirements

| Dependency | Version | Notes | |------------|---------|-------| | Node.js | ≥ 18 | Required | | Python | ≥ 3.8 | Auto-detected or nodpy install-python |

Python not installed?

nodpy install-python   # downloads to ~/.nodpy/python, no admin needed

VS Code

nodpy vscode    # installs syntax highlighting + .nodpy file icon

Installed automatically when you do npm install -g muk-nodpy if VS Code is detected.

Update / uninstall

nodpy upgrade             # update via npm
npm install -g muk-nodpy@latest   # manual

npm uninstall -g muk-nodpy
rm -rf ~/.nodpy           # remove portable Python + config

Environment variables

NODPY_PYTHON=/path/to/python3   # override Python binary
NODPY_DEBUG=1                   # print transformed JS before running

How it works

script.nodpy
    │
    ▼
Transformer         parse NodPy syntax → async JS + source map
    │
    ▼
Runtime             writes temp .mjs next to script (for node_modules resolution)
    │
    ├── JS/Node calls  → V8 (native Node.js)
    └── python calls   → Python Bridge
                              │
                              ▼
                         Python Worker (persistent subprocess)
                         JSON protocol over stdin/stdout
                         __nodpy_result__ = value  →  returned to JS

License

MIT