Skip to content

PEP 783: Clarify that PyEmscripten platform is independent of Python #4863

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hoodmane wants to merge 2 commits into
base: main
Choose a base branch
from
+49 −37
Open

PEP 783: Clarify that PyEmscripten platform is independent of Python #4863

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
180b08c
PEP 783: Clarify that PyEmscripten platform is independent of Python
hoodmane Mar 16, 2026
0c023d0
Add comment that application build implies shared library build
hoodmane Mar 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 49 additions & 37 deletions peps/pep-0783.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ benefit to being able to update the ABI.

In order to balance the ABI stability needs of package maintainers with the ABI
flexibility to allow the platform to move forward, Pyodide plans to adopt a new
ABI for each feature release of Python which we call
Emscripten platform for each feature release of Python which we call
``pyemscripten_${YEAR}_${PATCH}``.

The Pyodide team also coordinates the ABI flags that Pyodide uses with the
Expand Down Expand Up @@ -99,44 +99,54 @@ The platform tags will take the form:
Each one of these will be used with a specified Python version. For example, the
platform tag ``pyemscripten_2026_0`` will be used with Python 3.14.

Emscripten Wheel ABI
--------------------
The PyEmscripten Platform
-------------------------

The specification of the ``pyemscripten_<abi>`` platform includes:
The specification of the ``pyemscripten_${YEAR}_${PATCH}`` platform includes:

* Which version of the Emscripten compiler is used
* What libraries are statically linked with the interpreter
* What libraries are statically linked to the application
* What stack unwinding ABI is to be used
* How the loader handles dependency lookup
* That libraries cannot use ``-pthread``
* That libraries should be linked with ``-sWASM_BIGINT``

The ABI is selected by choosing the appropriate version of the Emscripten
compiler and passing appropriate compiler and linker flags. It is possible for
other people to build their own Python interpreter that is compatible with the
Pyodide ABI, it is not necessary to use the Pyodide distribution itself.
The platform is selected by choosing the appropriate version of the Emscripten
compiler and passing appropriate compiler and linker flags.

The Pyodide ABIs are fully specified in the `Pyodide Platform ABI
<https://pyodide.org/en/stable/development/abi.html>`__ documentation.
The platform definition does not include anything about Python and in particular
it is agnostic to the Python version it is intended to be used with. However,
for clarity we will note in the platform documentation which Python version we
plan to use each platform with.

The ``pyodide build`` tool knows how to create wheels that match the Pyodide
ABI. Unlike with manylinux wheels, there is no need for a Docker container to
build the ``pyemscripten_<abi>`` wheels. All that is needed is a Linux machine and
appropriate versions of Python, Node.js, and Emscripten.
The PyEmscripten platforms are fully specified in
`Pyodide's documentation on the PyEmscripten Platform <https://pyodide.org/en/stable/development/abi.html>`__.

It is possible to validate a wheel by installing and importing it into the
To define the platform we need only indicate how the main application is
compiled and linked. This implies how to build a compatible shared library.
However, our documentation includes detailed instructions on how to build a
compatible shared library because we assume most people will be building shared
libraries.

The ``pyodide build`` tool knows how to create wheels that are compatible with the
PyEmscripten platform. Unlike with manylinux wheels, there is no need for a
Docker container to build ``pyemscripten`` wheels. All that is needed is a Linux
machine and appropriate versions of Python, Node.js, and Emscripten.

It is possible to validate that a wheel is compatible with the PyEmscripten
platform by installing and importing it into an appropriate version of the
Pyodide runtime. Because Pyodide can run in an environment with strong
sandboxing guarantees, doing this produces no security risks.

Determining the ABI version
---------------------------
Determining the PyEmscripten Platform Version
---------------------------------------------

The ABI version is stored in the ``PYEMSCRIPTEN_ABI_VERSION`` config variable
and can be determined via:
The PyEmscripten platform version is stored in the
``PYEMSCRIPTEN_PLATFORM_VERSION`` config variable and can be determined via:

.. code-block:: python

pyemscripten_abi_version = sysconfig.get_config_var("PYEMSCRIPTEN_ABI_VERSION")
pyemscripten_platform_version = sysconfig.get_config_var("PYEMSCRIPTEN_PLATFORM_VERSION")


To generate the list of compatible tags, one can use the following code:
Expand All @@ -146,9 +156,9 @@ To generate the list of compatible tags, one can use the following code:
from packaging.tags import cpython_tags, _generic_platforms

def _emscripten_platforms() -> Iterator[str]:
pyemscripten_abi_version = sysconfig.get_config_var("PYEMSCRIPTEN_ABI_VERSION")
if pyemscripten_abi_version:
yield f"pyemscripten_{pyemscripten_abi_version}_wasm32"
pyemscripten_platform_version = sysconfig.get_config_var("PYEMSCRIPTEN_PLATFORM_VERSION")
if pyemscripten_platform_version:
yield f"pyemscripten_{pyemscripten_platform_version}_wasm32"
yield from _generic_platforms()

emscripten_tags = cpython_tags(platforms=_emscripten_platforms())
Expand All @@ -162,8 +172,8 @@ Package Installers

Installers should use the ``_emscripten_platforms()`` function shown above to
determine which platforms are compatible with an Emscripten build of CPython. In
particular, the ABI version is exposed via
``sysconfig.get_config_var(" PYEMSCRIPTEN_ABI_VERSION")``.
particular, the PyEmscripten platform version is exposed via
``sysconfig.get_config_var("PYEMSCRIPTEN_PLATFORM_VERSION")``.

Package Indexes
---------------
Expand Down Expand Up @@ -219,20 +229,21 @@ Alternative Options for the Platform Tag
``pyemscripten`` platform has nothing specifically to do with Python and
indeed can be used by any program that uses the appropriate version of
Emscripten and the appropriate link flags. But
``emscripten_${EMSCRIPTEN_VERSION}`` is too vague by itself because the ABI
``emscripten_${EMSCRIPTEN_VERSION}`` is too vague by itself because the platform
also depends on various linker flags.

There are other communities which have similar problems and would also benefit
from a centralized standard for "Long Term Service" ABIs that the whole
ecosystem could use. However, the Emscripten team have so far not been willing
to provide a this standard since they consider dynamic linking an unusual use
case. Thus it is left for our ecosystem to solve the problem itself. The
platform tag should contains some indication of this.
There are other communities which have similar problems and would also
benefit from a centralized standard for "Long Term Service" Emscripten
platforms that the whole ecosystem could use. However, the Emscripten team
have so far not been willing to provide a this standard since they consider
dynamic linking an unusual use case. Thus it is left for our ecosystem to
solve the problem itself. The platform tag should contains some indication
of this.

``pyemscripten_${PYTHON_MAJOR_MINOR}_${PATCH}``
This would make it clearer which Python version is meant for use with each
ABI, but it leads to conceptual confusion since the platform has nothing to do
with Python.
platform, but it leads to conceptual confusion since the platform has
nothing to do with Python.

``pyodide_...``
For now the platform is defined by Pyodide so this connection would be made
Expand All @@ -242,7 +253,7 @@ Alternative Options for the Platform Tag
also more forwards compatible to a future where the definition of the platform
moves upstream of Pyodide.

No ABI patch version
No patch version
We hope never to need the patch version, but it's good to be prepared for
unforseen problems.

Expand All @@ -253,7 +264,8 @@ Fo Pyodide Users
----------------
We recommend the `Pyodide documentation on installing packages
<https://pyodide.org/en/stable/usage/loading-packages.html>`__. We will make a
table showing which ``pyemscripten`` ABI each Pyodide version is compatible with.
table showing which ``pyemscripten`` platform version each Pyodide version is
compatible with.

For Package Maintainers
-----------------------
Expand Down
Loading