Skip to main content

​
Runtime

PythonRuntime uses Pyodide 0.28.3 (CPython compiled to WebAssembly via Emscripten) running in a Node.js Worker thread.

​
Support Tiers

TierLabelMeaning
1BridgeImplemented via worker-to-host RPC through the system driver.
2Pyodide built-inAvailable through Pyodide’s bundled standard library.
3BlockedIntentionally disabled; deterministic error on use.

​
Compatibility Matrix

​
Bridge capabilities (Tier 1)

These features use the same permission-gated system driver as the Node runtime.
CapabilityAPINotes
File readsecure_exec.read_text_file(path)Requires permissions.fs. Returns EACCES if denied, ENOSYS if no filesystem adapter.
File writeopen(path, "w")Requires permissions.fs.
Networksecure_exec.fetch(url, options)Requires permissions.network. Returns EACCES if denied, ENOSYS if no network adapter.
Environmentos.environFiltered by permissions.env. Only allowed keys are visible.
Working directoryos.getcwd() / os.chdir()Per-execution cwd override supported.
stdioprint() / input()print() streams through onStdio hook. input() reads from stdin option.

​
Standard library (Tier 2)

These modules are available through Pyodide’s bundled CPython standard library. This is not an exhaustive list; most pure-Python stdlib modules work.
ModuleStatus
jsonFull support.
osPartial. os.environ, os.getcwd(), os.chdir(), os.makedirs(), os.path.* work. Subprocess and signal APIs are unavailable (Emscripten limitation).
sysFull support. sys.modules persists across warm executions.
mathFull support.
reFull support.
datetimeFull support.
collectionsFull support.
itertoolsFull support.
functoolsFull support.
typingFull support.
ioFull support.
hashlibFull support.
base64Full support.
structFull support.
dataclassesFull support.
enumFull support.
abcFull support.

​
Blocked (Tier 3)

FeatureError
micropip / package installationERR_PYTHON_PACKAGE_INSTALL_UNSUPPORTED: Python package installation is not supported in this runtime
loadPackagesFromImportsSame as above.
loadPackageSame as above.
Subprocess spawningsecure_exec.spawn is not exposed.
Package installation keywords are detected before execution and fail deterministically.

​
Execution Model

​
Warm state

The Python interpreter stays alive per PythonRuntime instance. Consecutive exec() and run() calls share module globals and state: 
# First call
import sys
sys.modules[__name__].counter = 1

# Second call
import sys
print(sys.modules[__name__].counter)  # 1
To reset state, dispose and recreate the runtime.

​
Return values

run() returns structured results with value and globals: 
const result = await runtime.run<{ value: number; globals: Record<string, unknown> }>(
  "x = 2 + 2",
  { globals: ["x"] }
);
console.log(result.globals?.x); // 4

​
Serialization limits

Values crossing the bridge are serialized with these caps:
LimitValue
Object depth8 levels
Array elements1024
Object properties1024
Total payload4 MB
Circular referencesConverted to [Circular]

​
Differences from Node Runtime

NodePython
IsolationV8 isolate (isolated-vm)Pyodide in Worker thread
memoryLimitConfigurableNot available
timingMitigation"freeze" / "off"Not available
Return shapeexports (ESM default export)value + globals
Module systemCJS / ESMPython imports
Package installationHost node_modules overlayBlocked by design
Subprocesschild_process (permission-gated)Not available
HTTP serverhttp.createServer (bridge)Not available
State modelFresh per executionWarm (persistent across calls)

​
Timeout Behavior

Same contract as Node runtime:
  • cpuTimeLimitMs sets the CPU budget per execution
  • On timeout: code: 124, errorMessage: "CPU time limit exceeded"
  • Worker restarts after timeout for deterministic recovery
  • Subsequent executions work normally after a timeout