How we built a Python compiler that runs entirely in your browser

Our students learn Python in short lessons. Every lesson needs them to run code: in quick examples, in practice questions, in projects, and in a free-form compiler. Many of them are on a phone or a shared school laptop where they can't install anything.

The usual answer is a server that receives code, runs it in a container and sends the output back. We didn't want that:

• Running strangers' code on our servers is a security job of its own: sandboxing, resource limits, abuse.
• Cost grows with every Run click. A class of 40 students pressing Run every few seconds is a lot of containers.
• Latency. Every run is a network round trip, and input() becomes a chat between browser and server.

So we flipped it: ship Python to the browser once, and run everything on the student's device.

There are only three moving parts. Our server never sees or executes the program; it only serves static files.

Browsers only run JavaScript and WebAssembly (a compact binary format that runs at near-native speed). We use Pyodide, an open-source project that compiles the official CPython interpreter to WebAssembly. It is not a re-implementation: it is the same Python, so behaviour and error messages match what students will see on a real computer.

These are the files a browser downloads the first time (sizes measured from our build):

We self-host these files instead of loading them from a public CDN. A small build script copies them from the npm package into a versioned folder, public/pyodide/v314.0.7/. Because the version is in the path, the files never change, so we serve them with Cache-Control: immutable for a year. A second visit loads Python from the browser cache.

const installed = pkg.version;            // from node_modules/pyodide
const expected  = PYODIDE_VERSION;        // from src/lib/python/config.ts
if (installed !== expected) throw new Error("version mismatch");  // build fails

copy(["pyodide.mjs", "pyodide.asm.mjs", "pyodide.asm.wasm",
      "python_stdlib.zip", "pyodide-lock.json"], `public/pyodide/v${installed}`);
write("manifest.json", { version, sizes });   // used for the progress bar
removeOlderVersions();

Python runs in a Web Worker: a background thread with no access to the page. If a student writes while True: pass, only the worker is busy; buttons, scrolling and typing keep working, and the Stop button can still be pressed.

On the page side, one PythonEngineobject per tab owns the worker. It is a small state machine that every screen subscribes to (through React's useSyncExternalStore):

• Preload: opening the compiler starts the download straight away, so Python is usually ready before the first Run.
• Real progress bar: the worker streams the three big files itself, counts bytes against the sizes in manifest.json, and reports progress. Pyodide then loads them instantly from the HTTP cache.
• Live status:the header shows “Downloading Python · 42%”, “Starting Python”, then “Python 3.14.2 · runs in your browser”.

1. 1
   pageClears the output and sends { type: "run", code, stdin } to the worker.
2. 2
   workerIf the code imports a package such as numpy, installs it first (the status line shows progress).
3. 3
   workerConnects Python's stdout and stderr to the page and turns on line buffering, so each print appears as it happens.
4. 4
   workerRuns the code as a file called main.py in a fresh namespace, so variables from the previous run don't leak in.
5. 5
   workerBatches output and sends it every 40 ms or 4 KB, whichever comes first. Streaming without flooding the page.
6. 6
   pageAppends each chunk to the console: normal output in white, errors in red, typed input in green.
7. 7
   workerSends done with success or error and the run time, e.g. "finished in 12 ms".

py.setStdout({ write: (bytes) => emit("stdout", decode(bytes)) });
py.setStderr({ write: (bytes) => emit("stderr", decode(bytes)) });
py.runPython("import sys; sys.stdout.reconfigure(line_buffering=True)");

const ns = py.globals.get("dict")();       // fresh globals every run
ns.set("__name__", "__main__");
await py.runPythonAsync(code, { globals: ns, filename: "main.py" });

Beginners' programs are full of name = input("Your name? "). In a terminal, Python pauses until you type. But a browser never lets JavaScript pause and wait; everything is asynchronous. So how does Python, running inside JavaScript, stop in the middle of a line and wait for the keyboard?

The answer: the worker does block, on purpose, using a shared piece of memory that both threads can see.

The shared buffer has a tiny, fixed layout:

function waitForLine(id, sab) {
  const ctrl = new Int32Array(sab, 0, 2);
  Atomics.store(ctrl, 0, 0);                  // "I'm waiting"
  post({ type: "input-request", id });
  while (Atomics.load(ctrl, 0) === 0) Atomics.wait(ctrl, 0, 0);
  const len = Atomics.load(ctrl, 1);
  if (len < 0) return null;                   // Ctrl+D → EOFError in Python
  return new TextDecoder().decode(new Uint8Array(sab, 8, len).slice());
}

Three details that matter:

• One line per read. We give Python a low-level reader that returns exactly one typed line, like a terminal. A higher-level option kept asking for more lines before returning the first.
• Thinking time is free. The run timer is paused while the program waits for you, and restarts when you press Enter.
• Ctrl+D in an empty answer box sends “end of input”, which Python reports as EOFError, as in a real terminal.

Fallback: if a browser can't isolate the page, the compiler quietly switches to an Input box: you type every answer up front, one per line, and each input()takes the next line. The output still shows what was “typed” in green so it reads like a terminal session.

A raw Pyodide traceback includes many lines of interpreter internals. The worker cleans it up before it reaches the page:

• Keeps only the part that starts at File "main.py", the student's own code.
• Finds the line number, highlights that line in the editor, and shows a “Line 4 in main.py” link that jumps to it.
• Adds a plain-English hint for the most common beginner errors.
• The full traceback is still one click away for curious students.

We didn't pull in a heavyweight code-editor library. The editor is a normal <textarea>with transparent text, laid exactly over a coloured copy of the same code. You type into the real textarea, so the phone's own keyboard, selection, copy-paste and accessibility all work, and you see the coloured layer underneath.

Syntax colours come from a single regular expression that recognises comments, strings, keywords, common built-ins and numbers. It is deliberately simple: fast enough to re-colour on every keystroke.

Same component, same engine. Only the layout changes, using CSS breakpoints. No separate mobile app or mobile version.

• Code and input are autosaved to the browser's localStorage300 ms after you stop typing. Reload and it's still there. Nothing is uploaded.
• Examples menu loads ready programs (hello world, input(), loops, if/elif, lists and functions, random dice, star pattern).
• Open a .py file (up to 200 KB), Download main.py, and Copy: everything happens locally.
• Inside the course, lessons can hand code to the compiler with an “Open in compiler” button.

The standard library ships with the runtime. For anything else, the compiler reads the program's import lines before running and asks Pyodide to install matching packages (loadPackagesFromImports). The Pyodide distribution we use lists 357 packages, including numpy. They download from jsDelivr only the first time a program imports them, then the browser caches them.

Lesson exercises skip this step on purpose, so they start instantly.

• First load is a real download(about 6.3 MB compressed). On a slow connection the first Run takes a few seconds; after that it's cached.
• No desktop windows. tkinter (and turtle, which is built on it) need a window system that doesn't exist inside a browser tab.
• Only packages Pyodide has built for WebAssembly. If a library isn't in that list, you get ModuleNotFoundError with an explanation.
• Interactive input() needs a modern browser that supports cross-origin isolation; older ones get the Input box instead.
• Long jobs are cut off at 15 seconds. This is a learning tool, not a place to train models.
• Your code lives on one device. Clearing site data, or switching to another phone, starts fresh.