How PyScript Runs Python in Browsers via WebAssembly

PyScript allows developers to execute Python code natively within a client-side web browser without relying on a remote backend server. By leveraging WebAssembly (Wasm) and underlying runtime ports such as Pyodide and MicroPython, PyScript bridges Python execution directly with modern browser engines. This article breaks down the underlying architecture, explaining how compiled C-based runtimes, virtual file systems, and two-way JavaScript interoperability make browser-based Python execution possible.

The Foundation: WebAssembly (Wasm)

Web browsers inherently execute only three core technologies: HTML, CSS, and JavaScript. To run other programming languages natively, browser engines rely on WebAssembly.

WebAssembly is a low-level, binary instruction format designed as a portable compilation target for high-level languages like C, C++, and Rust. Modern browser engines—including Google Chrome's V8, Mozilla Firefox's SpiderMonkey, and Apple Safari's JavaScriptCore—include dedicated WebAssembly virtual machines. Because WebAssembly executes at near-native speed within a secure, sandboxed execution environment, it allows non-JavaScript runtimes to execute directly inside the browser tab.

Compiling Python to WebAssembly: Pyodide and MicroPython

Python is an interpreted language that requires an underlying interpreter to parse and execute scripts. Standard CPython is written in C. Consequently, running Python in the browser requires compiling the CPython interpreter itself into a WebAssembly binary.

PyScript relies on two primary runtime options:

  1. Pyodide: A port of CPython to WebAssembly built using the Emscripten compiler toolchain. Pyodide includes standard CPython, a foreign function interface (FFI) to JavaScript, and pre-compiled Wasm packages for major data science libraries like NumPy, Pandas, and Matplotlib.
  2. MicroPython: A lightweight, optimized implementation of Python 3 designed for microcontrollers and constrained environments, also compiled to Wasm. It offers significantly faster startup times and a smaller memory footprint than Pyodide, making it ideal for lightweight web applications.

PyScript acts as an orchestration layer above these runtimes, providing a unified interface to load, configure, and execute Python code.

The Step-by-Step Execution Lifecycle

When a web page containing PyScript loads, the browser follows a defined execution sequence:

  1. Bootstrap and Runtime Download: The browser encounters the PyScript JavaScript library linked in the HTML. PyScript initializes and determines whether to fetch the Pyodide or MicroPython WebAssembly module (.wasm file), along with the necessary JavaScript glue code.
  2. WebAssembly Instantiation: The browser compiles and instantiates the .wasm file in memory. At this stage, a complete Python interpreter is running inside the browser engine’s WebAssembly runtime.
  3. Environment Setup: PyScript constructs a virtual file system (typically backed by Emscripten's MEMFS) in the browser's memory. This mimics a standard operating system file system, allowing Python's import mechanisms to read modules and libraries.
  4. Parsing PyScript Tags: PyScript scans the DOM for custom tags such as <script type="py"> or <py-script>. It extracts the Python code within these elements and feeds it as a string to the running interpreter via the runtime's C-level evaluation functions.
  5. Execution: The WebAssembly-compiled interpreter parses, compiles to bytecode, and evaluates the Python instructions entirely within the client's memory sandbox.

JavaScript and DOM Interoperability

Python executing inside a WebAssembly sandbox cannot manipulate the browser's Document Object Model (DOM) directly. To solve this, PyScript uses a bidirectional foreign function interface (FFI) provided by the underlying runtime.

The runtime maps Python objects to JavaScript proxy objects and vice-versa. When a script runs:

from pyscript import document

element = document.querySelector("#output")
element.innerText = "Hello from Python!"

The underlying bridge translates the Python call into a JavaScript API call across the Wasm boundary. The browser engine executes the DOM mutation via its standard C++ and JavaScript internals, enabling full access to web APIs, event listeners, local storage, and Canvas rendering directly from Python.

Resource Management and Execution Context

Because standard browser execution is single-threaded, running long-running or computationally heavy Python scripts directly on the main thread can cause the user interface to freeze. Modern implementations of PyScript address this by utilizing Web Workers. By running the Python WebAssembly instance inside a background worker thread, PyScript keeps UI interactions smooth while coordinating with the main thread through asynchronous message passing.