pyodide.org

Pyodide is a Python distribution for the browser and Node.js based on WebAssembly. It is a port of CPython to WebAssembly/Emscripten, which means you can run Python — and install many Python packages — directly in a web page or a Node.js process without a separate Python server. This page explains what it can do, what it supports, and how to decide whether it fits your project.

What Pyodide actually is

Pyodide is not a reimplementation of Python. It is CPython itself, compiled to WebAssembly and run through Emscripten. That distinction matters: your code runs on the real CPython runtime, so language behavior, the standard library, and error semantics stay close to what you already expect.

It ships in two main environments:

• Browsers — Python runs inside the page, and when used in a browser it has full access to the Web APIs.
• Node.js — the same distribution runs server-side or in tooling.

What you can install and run

Package support is the part most people care about, and Pyodide's model is straightforward:

• Pure Python packages: any pure Python package with a wheel available on PyPI is supported, installed through micropip.
• Packages with native extensions: many packages with C, C++, and Rust extensions have been ported for use with Pyodide.

The ported set includes general-purpose libraries such as regex, PyYAML, and cryptography, plus scientific Python packages including NumPy, pandas, SciPy, Matplotlib, and scikit-learn.

The practical rule: if a package is pure Python with a wheel, expect it to work. If it has a compiled extension, check whether it has been ported before assuming it will load.

Mixing JavaScript and Python

Pyodide provides a robust JavaScript ⟺ Python foreign function interface, so you can freely mix the two languages in your code with minimal friction. The interface covers more than simple value passing:

• Error handling — throw an error in one language and catch it in the other.
• async/await — asynchronous work crosses the boundary rather than being trapped on one side.
• Web API access — Python running in a browser can reach the browser's own APIs.

This is what makes Pyodide useful beyond "run a script in a tab": you can keep your UI in JavaScript and your data or scientific logic in Python, and let them call each other.

Choosing how to use it

The right entry point depends on what you are doing:

If you just want to see it work, there is a REPL you can try directly in your browser with no installation needed.

When Pyodide is the right fit

Pyodide fits well when you need Python logic to run where the user already is — in the browser or in a Node.js process — and you want to avoid a round trip to a Python backend. It is a strong match for scientific and data work in the browser, given the ported NumPy/pandas/SciPy/Matplotlib/scikit-learn stack, and for interactive teaching or demos where installation would be a barrier.

It is a weaker fit when your dependencies rely on native extensions that have not been ported, or when your workload is heavy enough that downloading a WebAssembly runtime and packages to the client is the wrong trade-off. In those cases, a conventional Python server remains the simpler choice.

To go further, start with the Getting started documentation if you are consuming Pyodide, or the pyodide-build documentation if you are packaging for it.

Pyodide supports any pure Python package that has a wheel available on PyPI, and it also ships with many packages that have C, C++, or Rust extensions already ported for use with it. You install additional packages at runtime with micropip. If a package you need is pure Python and published as a wheel, it should work; if it has compiled extensions, check whether it is already in the Pyodide distribution or has been ported.

What Pyodide is

Pyodide is a port of CPython to WebAssembly/Emscripten, distributed as a Python distribution for the browser and Node.js. It makes it possible to install and run Python packages in the browser with micropip.

When used inside a browser, Python has full access to the Web APIs. Pyodide also provides a JavaScript ⟺ Python foreign function interface, so you can mix the two languages in your code, including error handling across the boundary (throw an error in one language, catch it in the other) and async/await.

Which packages are supported

The practical rule: start from the wheel. A pure Python package with a wheel available on PyPI is supported. For anything with compiled extensions, the package either needs to be part of the Pyodide distribution or have been ported; the list above covers many common cases, but it is not a guarantee for every package.

How to install and run packages

Packages are installed in the browser with micropip. The general flow is:

1. Load Pyodide in your page or Node.js environment.
2. Use micropip to install the package you need.
3. Import and use it like normal Python.

The expected result is that the package is fetched and made available to your Python code running in the same environment. If installation fails, the usual cause is that the package is not pure Python and has no port available for Pyodide.

Where to go next

• Use a hosted distribution of Pyodide: see the Getting started documentation.
• Host Pyodide yourself: download it from the releases page and serve it with a web server.
• Use Pyodide with a bundler: see the documentation on Working with Bundlers.
• Maintain a Python package: see the pyodide-build documentation.
• Add a package to the Pyodide distribution: see the pyodide-build documentation.
• Experiment with or contribute to the runtime: see the documentation on Building from source.

You can also try Pyodide in a REPL directly in your browser with no installation needed.

Start by identifying your role, then jump to the matching documentation path. Pyodide is a Python distribution for the browser and Node.js based on WebAssembly, and its docs are organized by task rather than as a single linear tutorial.

Pick your path

What Pyodide actually gives you

Knowing the scope helps you choose the right entry point:

• It is a port of CPython to WebAssembly/Emscripten.
• You can install and run Python packages in the browser with micropip.
• Any pure Python package with a wheel on PyPI is supported.
• Many packages with C, C++, and Rust extensions have also been ported, including general-purpose ones such as regex, PyYAML, and cryptography, plus scientific packages like NumPy, pandas, SciPy, Matplotlib, and scikit-learn.
• A JavaScript ⟺ Python foreign function interface lets you mix the two languages, with full error handling (throw in one language, catch in the other), async/await, and more.
• In a browser, Python has full access to the Web APIs.

Try it before you read anything

If you just want to see it work, run Pyodide in a REPL directly in your browser — no installation needed. That is the fastest way to confirm it fits your use case before committing to a hosting or build path.

After you choose a path

Once you are past the entry point, the Using Pyodide section covers the practical ground: Getting started, downloading and deploying, accessing files, the quick reference, loading packages, Python compatibility, type translations, interrupting execution, redirecting standard streams, the API reference, and a FAQ. The Development section is for contributors, covering building packages, building from source, testing and benchmarking, debugging tips, and how to contribute.

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.

You can try Pyodide directly in your browser through a REPL (read-eval-print loop) on pyodide.org — no installation, no local Python environment, and no server setup required. This is the fastest way to run Python code in the browser and confirm what Pyodide can do before committing to a hosted or self-hosted setup.

What the in-browser REPL gives you

Pyodide is a Python distribution for the browser and Node.js based on WebAssembly. It is a port of CPython to WebAssembly/Emscripten, so the REPL runs an actual CPython interpreter compiled for the browser rather than a JavaScript reimplementation of Python.

In the REPL you can:

• Execute Python code interactively and see results immediately.
• Install and run Python packages in the browser with micropip.
• Use many scientific and general-purpose packages that have been ported to Pyodide, including NumPy, pandas, SciPy, Matplotlib, scikit-learn, regex, PyYAML, and cryptography.
• Mix Python and JavaScript through Pyodide's foreign function interface, including error handling across the two languages and async/await.
• Access Web APIs from Python when running inside a browser.

Steps to try it

1. Open the Pyodide site (pyodide.org) and go to the "Try Pyodide" section, which links to a REPL that runs directly in your browser.
2. Wait for the runtime to load. The first load downloads the WebAssembly build, so it can take a moment on a slow connection.
3. Type Python at the prompt and run it. For example, enter a simple expression or a short script and check the output.
4. To use a package, load it with micropip inside the REPL, then import it. Any pure Python package with a wheel available on PyPI is supported; many packages with C, C++, or Rust extensions have also been ported.

Expected result: your Python code executes in the browser tab and prints output in the REPL, with no files installed on your machine.

Common snags

• First load is slow. The WebAssembly runtime and any packages you load are fetched over the network, so the initial experience depends on your connection.
• Not every package works. Pure Python packages with a PyPI wheel are supported, and many extension packages have been ported, but a package that has not been built for Pyodide will not load. Check the Pyodide distribution before assuming a package is available.
• Browser memory limits apply. Large datasets or heavy computation may hit the tab's memory ceiling.
• The REPL is for experimentation. It is a quick way to validate behavior, not a deployment target. For production use you would host Pyodide yourself or use a hosted distribution.

Where to go next

• To use a hosted distribution of Pyodide, see the Getting started documentation.
• To host Pyodide yourself, download it from the releases page and serve it with a web server.
• To use Pyodide with a bundler, see the Working with Bundlers documentation.
• If you maintain a Python package, or want to add a package to the Pyodide distribution, see the pyodide-build documentation.
• To experiment with or contribute to the runtime itself, see Building from source.