PEP 816: WASI Support (#4732)

Co-authored-by: Jelle Zijlstra <[email protected]>

Author: brettcannon

.github/CODEOWNERS

@@ -687,8 +687,10 @@ peps/pep-0808.rst  @FFY00
 peps/pep-0809.rst  @zooba
 peps/pep-0810.rst  @pablogsal @DinoV @Yhg1s
 peps/pep-0811.rst  @sethmlarson @gpshead
+# ...
 peps/pep-0814.rst  @vstinner @corona10
 peps/pep-0815.rst  @emmatyping
+peps/pep-0816.rst  @brettcannon
 # ...
 peps/pep-2026.rst  @hugovk
 # ...

peps/pep-0816.rst

@@ -0,0 +1,172 @@
+PEP: 816
+Title: WASI Support
+Author: Brett Cannon <[email protected]>
+Discussions-To: Pending
+Status: Draft
+Type: Informational
+Created: 05-Nov-2025
+Post-History: Pending
+
+
+Abstract
+========
+
+This PEP outlines the expected support for WASI_ by CPython. It contains enough
+details to know what WASI and WASI SDK version is expected to be supported for
+any release of CPython while official WASI support is specified in :pep:`11`.
+
+
+Motivation
+==========
+
+CPython has supported WASI according to :pep:`11` since Python 3.11. As part of
+this support, CPython needs to target two different things: the WASI_ version
+and the `WASI SDK`_ version (both of whose development is driven by the
+`Bytecode Alliance`_). The former is the specification of WASI itself while the
+latter is a version of clang_ with a specific version of wasi-libc_ as the
+sysroot that allows for compiling CPython to WASI. There is roughly an annual
+release cadence for new WASI versions while there's no set release cadence for
+WASI SDK.
+
+Agreeing on which WASI and WASI SDK versions to support allows for clear
+targeting of the CPython code base towards those versions. This also lets the
+community set appropriate expectations as to what will (not) be considered a
+bug if it only manifests itself under a certain WASI or WASI SDK version. It
+also provides the community an overall target for WASI and WASI SDK for any
+specific Python version when building other software like libraries. This is
+important as WASI SDK is NOT forwards- or backwards-compatible due to the ABI
+of wasi-libc not making any compatibility guarantees, making broad coordination
+important so code works together.
+
+This coordination and recording around version targets can be important in
+situations where the selected version is non-obvious. For example, WASI SDK 26
+and 27 have a `bug <https://github.com/WebAssembly/wasi-libc/issues/617>`__
+which cause CPython to hang in certain situations (including exiting the REPL).
+Because the bug is in thread support code it wouldn't necessarily be obvious to
+others in the community that CPython will not target those versions and thus
+3rd-party code should also avoid those versions.
+
+
+Rationale
+=========
+
+While technically separate, CPython cannot support a version of WASI until WASI
+SDK supports it. WASI versions are considered backwards-compatible with each
+other, but WASI SDK is NOT compatible forwards or backwards thanks to wasi-libc
+not having ABI compatibility guarantees. As such, it's important to set support
+expectations for a specific WASI SDK version in CPython. Historically, the
+support difference between WASI SDK versions for CPython have involved settings
+in the ``config.site`` file that is maintained for WASI. Support issues have
+come up due to bugs in WASI SDK itself. Finally, new features being supported
+by WASI SDK can also cause code that wasn't previously used in a WASI build to
+suddenly be run which can require code updates to pass tests.
+
+As for WASI version support, that typically translates into what stdlib modules
+are (potentially) usable with a WASI build. For example, WASI 0.2 added socket
+support and WASI 0.3.1 is scheduled to have some form of threading support.
+Knowing what WASI version is supported sets expectations for what stdlib
+modules should be supported.
+
+Interpreter feature availability can be dependent on the WASI version. For
+instance, until there is threading support there can't be free-threading
+support in WASI. Once again, this helps set expectations of what should be
+working based on the target WASI version.
+
+
+Specification
+=============
+
+The WASI and WASI SDK version supported by a CPython version in CI or its
+stable Buildbot builder when b1 is released MUST be the version to be supported
+for the lifetime of that Python version after this PEP is accepted. If there is
+a discrepancy between CI and the Buildbot builder for some reason, the WASI
+maintainers as specified by :pep:`11` will choose which sets of versions will
+be designated as the versions to support.
+
+The WASI version and WASI SDK version supported for a Python version MUST be
+recorded in :pep:`11` as an official record.
+
+If for some reason a supported WASI SDK version needs to change after being
+recorded, a note will be made in :pep:`11` as to when and why the change was
+made. Such a change is at the discretion of the maintainers of WASI support as
+listed in :pep:`11` and does not require steering council approval. The
+expectation, though, is that such a change SHOULD NOT occur.
+
+Changing the WASI version after it has been recorded MUST NOT occur UNLESS the
+steering council approves it. This is due to the increased support burden for
+new WASI versions and the shift in expectations of what CPython would support
+when support expectations have already been set.
+
+Any updates to :pep:`11` to reflect the appropriate WASI version for the target
+triple for the main branch MUST be made as needed, but it does NOT require
+steering council approval to update. The steering council is spared needing to
+approve such an update as it does not constitute a new platform and is more in
+line with a new OS release which currently does not require steering council
+approval.
+
+
+Designated Support
+==================
+
+Note that while WASI SDK in some places lists both a major and minor version,
+in actuality the minor version has never been set to anything other than ``0``
+and there's an expectation that
+`any minor version will be ABI compatible with the overall major version <https://bytecodealliance.zulipchat.com/#narrow/channel/219900-wasi/topic/Platform.20tags.20for.20packages.20targeting.20WASI/near/516771862>`__.
+As well, the WASI community only refers to WASI SDK versions by their major
+version due to there having never been a minor release. Subsequently, this PEP
+only records the major version of WASI SDK until such time that there's a need
+to record a minor version.
+
+====== ==== ========
+Python WASI WASI SDK
+====== ==== ========
+3.14   0.1  24
+3.13   0.1  24
+3.12   0.1  16
+3.11   0.1  16
+====== ==== ========
+
+
+Notes
+-----
+
+All versions prior to Python 3.15 predate this PEP. The version support for
+those versions is based on what was supported when this PEP was written.
+
+WASI was a tier 3 platform according to :pep:`11` for Python 3.11 and 3.12.
+WASI became a tier 2 platform starting with Python 3.13.
+
+WASI 0.2 support has been skipped due to lack of time, to the point that it was
+deemed better to go straight to WASI 0.3 instead. This is based on a
+recommendation from the `Bytecode Alliance`_.
+
+WASI SDK 26 and 27 have a
+`bug <https://github.com/WebAssembly/wasi-libc/issues/617>`__ which causes
+CPython to hang in certain situations, and so they have been skipped.
+
+
+Acknowledgements
+================
+
+Thanks to Joel Dice and Ben Brandt of the Python
+`sub-group <https://github.com/bytecodealliance/SIG-Guest-Languages/blob/main/docs/subgroups.md>`__
+of the
+`guest languages SIG <https://github.com/bytecodealliance/SIG-Guest-Languages>`__
+of the `Bytecode Alliance`_ for discussing the specification of this PEP.
+
+
+Footnotes
+=========
+
+.. _WASI: https://wasi.dev
+.. _WASI SDK: https://github.com/WebAssembly/wasi-sdk
+.. _wasi-libc: https://github.com/WebAssembly/wasi-libc
+.. _clang: https://clang.llvm.org
+.. _Bytecode Alliance: https://bytecodealliance.org
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.