dspy.PythonInterpreter¶

Deno Installation¶

PythonInterpreter uses Deno and Pyodide to run Python in a local WASM sandbox. The recommended installation keeps Deno in the same Python environment as DSPy:

pip install "dspy[deno]"

The deno extra installs the official Deno Python distribution (>=2.4.5,<3.0.0). DSPy prefers that managed binary when it is installed, so Python dependency locking also locks the Deno runtime. The extra provides binaries for macOS x86-64/arm64, glibc Linux x86-64/arm64, and Windows x86-64 and adds approximately 40–50 MiB to the environment.

On other platforms, install a compatible Deno 2.x release (>=2.0.0,<3.0.0) using the Deno installation instructions. DSPy falls back to the deno executable on PATH. An explicit deno_command passed to PythonInterpreter takes precedence over both options.

DSPy disables ambient deno.json, lockfile, package.json, and local node_modules discovery for its default runner. A package.json in the current directory or an ancestor therefore cannot redirect the sandbox’s pinned Pyodide dependency. No DENO_NO_PACKAGE_JSON environment variable is required.

`dspy.PythonInterpreter(deno_command: list[str] | None = None, enable_read_paths: list[PathLike | str] | None = None, enable_write_paths: list[PathLike | str] | None = None, enable_env_vars: list[str] | None = None, enable_network_access: list[str] | None = None, sync_files: bool = True, tools: dict[str, Callable[..., str]] | None = None, output_fields: list[dict] | None = None, callbacks: list[BaseCallback] | None = None)` ¶

Local interpreter for secure Python execution using Deno and Pyodide.

Implements the Interpreter protocol for secure code execution in a WASM-based sandbox. Code runs in an isolated Pyodide environment with no access to the host filesystem, network, or environment by default.

Prerequisites

Install the managed Deno runtime with pip install "dspy[deno]", or install a compatible Deno 2.x release system-wide.

Examples:

# Basic execution
with PythonInterpreter() as interp:
    result = interp("print(1 + 2)")  # Returns "3"

# With host-side tools
def my_tool(question: str) -> str:
    return "answer"

with PythonInterpreter(tools={"my_tool": my_tool}) as interp:
    result = interp("print(my_tool(question='test'))")

Parameters:

Name	Type	Description	Default
`deno_command`	`list[str] \| None`	command list to launch Deno.	`None`
`enable_read_paths`	`list[PathLike \| str] \| None`	Files or directories to allow reading from in the sandbox.	`None`
`enable_write_paths`	`list[PathLike \| str] \| None`	Files or directories to allow writing to in the sandbox. All write paths will also be able to be read from for mounting.	`None`
`enable_env_vars`	`list[str] \| None`	Environment variable names to allow in the sandbox.	`None`
`enable_network_access`	`list[str] \| None`	Domains or IPs to allow network access in the sandbox.	`None`
`sync_files`	`bool`	If set, syncs changes within the sandbox back to original files after execution.	`True`
`tools`	`dict[str, Callable[..., str]] \| None`	Dictionary mapping tool names to callable functions. Each function should accept keyword arguments and return a string. Tools are callable directly from sandbox code by name.	`None`
`output_fields`	`list[dict] \| None`	List of output field definitions for typed SUBMIT signature. Each dict should have ‘name’ and optionally ‘type’ keys.	`None`
`callbacks`	`list[BaseCallback] \| None`	Optional instance-level callback handlers.	`None`