How does Pyodide handle JavaScript and Python interoperability?

Updated

Pyodide provides a foreign function interface (FFI) between JavaScript and Python, so you can call functions and pass values across the two languages in the same program. It supports error handling across the boundary — an error thrown in one language can be caught in the other — and it supports async/await. This applies when you run Pyodide in a browser or in Node.js, since both environments are covered by the same runtime.

What the interface lets you do

The FFI is described as robust and designed so the two languages can be mixed "with minimal friction." In practice that means:

  • Call across languages. JavaScript can call Python functions, and Python can call JavaScript functions, without writing a separate bridge layer for each one.
  • Pass values both ways. Objects and values cross the boundary rather than staying trapped on one side.
  • Handle errors across the boundary. If Python raises an error, JavaScript can catch it; if JavaScript throws, Python can catch it. You don't have to convert every failure into a generic string first.
  • Use async/await. Asynchronous code is supported across the interface, so you can await work that originates on the other side.

Why this matters in a browser

When Pyodide runs inside a browser, Python has full access to the Web APIs. Combined with the FFI, that means Python code can reach browser capabilities and JavaScript code can reach Python libraries in the same page, rather than running as two isolated programs.

A concrete example of the pattern

Suppose you have a Python function that parses a data file and a JavaScript function that renders the result to the page. With the FFI, the flow is:

  1. JavaScript calls the Python parsing function and passes in the file contents.
  2. Python returns a result object.
  3. JavaScript receives that object and passes it to the render function.
  4. If the Python parser raises an error, JavaScript catches it and shows a message instead of failing silently.

The same flow works in reverse: Python can call a JavaScript function and catch an error it throws.

What you need before mixing the languages

  • A working Pyodide runtime, either loaded in a browser or run under Node.js.
  • The Python packages you intend to call. Pure Python packages with a wheel on PyPI are supported; many packages with C, C++, and Rust extensions have also been ported, including regex, PyYAML, cryptography, NumPy, pandas, SciPy, Matplotlib, and scikit-learn.
  • micropip if you need to install packages at runtime in the browser.

Where to go next

If you want to try the interface before setting anything up, Pyodide offers a REPL directly in the browser with no installation required. For a hosted distribution, the Getting started documentation is the entry point; if you host Pyodide yourself, download it from the releases page and serve it with a web server. If you use a bundler, see the Working with Bundlers documentation.