Text of peps.python.org › pep-0776 as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 776 – Emscripten Support | peps.python.org

PEP 776 – Emscripten Support PEP 776 – Emscripten Support Author : Hood Chatham <roberthoodchatham at gmail.com> Sponsor : Łukasz Langa <lukasz at python.org> Discussions-To : Discourse thread Status : Active Type : Informational Created : 18-Mar-2025 Python-Version : 3.14 Post-History : 18-Mar-2025 , 28-Mar-2025 Resolution : 04-Apr-2026 Table of Contents Abstract Motivation Emscripten Platform Information “Pyodide” vs “Emscripten Python” Background on Emscripten POSIX Compliance Development Tools Emscripten Application Lifecycle File System Setup The Standard Library Third-party packages Console and Interactive Usage Traps and Uncaught Exceptions Specification Scope of Work Linkage Standard Library Unsupported Modules Removed Modules Included but not Working Modules Platform Identification Signals Support Function Pointer Casts CI Resources PEP 11 Future Work Improving Cross Builds in the Packaging Ecosystem Pyodide Runtime Features to be Upstreamed JavaScript API for Bootstrapping JavaScript foreign function interface (FFI) Asyncio Backwards Compatibility Security Implications How to Teach This Reference Implementation Copyright Abstract Emscripten is a complete open source compiler toolchain.

It compiles C/C++ code into WebAssembly/JavaScript executables, for use in JavaScript runtimes, including browsers and Node.js. The Rust language also maintains an Emscripten target. This PEP formalizes the addition of Tier 3 for Emscripten support in Python 3.14 which was approved by the Steering Council on October 25, 2024 . The goals are: To describe the current state of the CPython Emscripten runtime To describe the current state of the Pyodide runtime To identify minor features to be upstreamed from the Pyodide runtime into the CPython Emscripten runtime The minor features identified here are all features that could be implemented without a PEP.

We discuss more significant runtime features that we would like to implement but we defer decisions on those features to subsequent PEPs. Motivation A web browser is a universal computing platform, available on Windows, macOS, Linux, and every smartphone. The Pyodide project has supported Emscripten Python since 2018. Hundreds of thousands of students have learned Python through Pyodide via projects like Capytale and PyodideU .

Pyodide is also increasingly being used by Python packages to provide interactive documentation. This demonstrates both the importance and the maturity of the Emscripten platform. Emscripten and WASI are also the only supported platforms that offer any meaningful sandboxing. Emscripten Platform Information “Pyodide” vs “Emscripten Python” For the sake of this document, we use the term “Emscripten Python” to refer to the Emscripten Python maintained in the python/cpython repository, without any downstream additions.

We contrast the features present in Emscripten Python to the features present in Pyodide. Pyodide is maintained on GitHub and distributed via jsDelivr , npm , and GitHub releases . Emscripten Python is not distributed, but it is possible to build by following the instructions in the devguide Background on Emscripten Emscripten consists of a C and C++ compiler and linker based on LLVM , together with a runtime based on a mildly patched musl libc.

Emscripten is a POSIX-based platform. It uses the WebAssembly binary format , and the WebAssembly dynamic linking section . The emcc compiler is a wrapper around clang . The emcc linker is a wrapper around wasm-ld ( also part of the LLVM toolchain ). Emscripten support for portable C/C++ code source compatibility with Linux is fairly comprehensive, with certain expected exceptions to be spelled out. CPython already supports compilation to Emscripten, and it only requires a very modest number of modifications to the normal Linux target.

POSIX Compliance Emscripten is a POSIX platform. However, there are POSIX APIs that exist but always fail when called and POSIX APIs that don’t exist at all. In particular, there are problems with networking APIs and blocking I/O, and there is no support for fork() . See Emscripten Portability Guidelines . Emscripten executables can be linked with threading support, but it comes with several limitations: Enabling threading requires websites to be served with special security headers that indicate acceptance of the possibility of Spectre -style information leakage.

These headers are a usability hazard for users who are not intimately familiar with the web platform. If an executable is linked with both threading and a dynamic loader, Emscripten prints a warning that using dynamic loading and pthreads together is experimental. It may cause performance problems or crashes. These problems may require WebAssembly standards work to resolve. Because of these limitations, Pyodide standardizes a no-pthreads build of Python.

If there is sufficient demand, a pthreads build with no dynamic loader could be added later. Development Tools Emscripten development tools are equally well supported on Linux, Windows, and macOS. The upstream tools include: The Emscripten Software Developer Kit ( emsdk ) which can be used to install the Emscripten compiler toolchain ( emcc ). emcc is a C and C++ compiler, linker, and a sysroot with headers for the system libraries.

The system libraries themselves are generated on the fly based on the ABI requested. Node.js can be used as an “emulator” to run Emscripten programs from the command line. This emulation behaves best on Linux with macOS as a runner up. Node.js is the most convenient way to test Emscripten programs. It is possible to run Emscripten programs inside of any web browser. Browser automation tools like Selenium, Playwright, or Puppeteer can be used to test features that are browser-only.

Pyodide’s tools: pyodide build can be used to cross compile Python packages to run on Emscripten. Cross compilation works best on Linux, there is experimental support on macOS, and it is entirely unsupported on Windows. pyodide venv can make a virtual environment that runs in Pyodide. pytest-pyodide can test Python code against various JavaScript runtimes. cibuildwheel supports building wheels to target Emscripten using pyodide build .

In the short term, Pyodide’s packaging tooling will stay in the Pyodide repository. It is an open question where Pyodide’s packaging tooling should live in the long term. Two sensible options would be for it to remain under the pyodide organization or be moved into the pypa organization on GitHub. Emscripten Application Lifecycle An Emscripten “binary” consists of a pair of files, an .mjs file and a .wasm file.

The .wasm file contains all of the compiled C/C++/Rust code. The .mjs file contains the lifecycle code to set up the runtime, locate the .wasm file, compile it, instantiate it, call the main() function, and to shut down the runtime on exit. It also includes an implementation for all of the system calls, including the file system, the dynamic loader, and any logic to expose additional functionality from the JavaScript runtime to C code.

The .mjs file exports a single bootstrapEmscriptenExecutable() JavaScript function that bootstraps the runtime, calls the main() function, and returns an API object that can be used to call C functions. Each time it is called produces a complete and independent copy of the runtime with its own separate address space. The bootstrapEmscriptenExecutable() takes a large number of runtime settings. The full list is described in the Emscripten documentation here.

The most important of these are as follows: thisProgram : The value of argv[0] . In Python, this makes its way into sys.executable . arguments : The list of string arguments to be passed to main() . preRun : A list of callbacks which are invoked after the JavaScript runtime and file system have been bootstrapped but before calling main() . Useful to set up the file system, environment variables, and standard streams. print / p

The rest of this page is on the live site.