Managing Cross-Build Environments

Managing Cross-Build Environments#

The cross-build environment (xbuildenv) contains everything needed to cross-compile Python packages for WebAssembly: CPython headers, sysconfig data, and the Emscripten SDK. pyodide-build installs it automatically on first use, but you can also manage it explicitly.

Installing#

The pyodide xbuildenv install command installs the cross-build environment.

You must have the same host Python version as the one used to build the cross-build environment. If you have a different Python version, the installation will fail.

We recommend using uv or pyenv to manage your Python versions.

# Install the latest compatible version
pyodide xbuildenv install

# Install a specific Pyodide version
pyodide xbuildenv install 0.29.3

# Install from a custom URL
pyodide xbuildenv install --url https://example.com/xbuildenv-0.27.0.tar

# Force install even if version compatibility check fails
pyodide xbuildenv install --force

# Install the latest nightly release
pyodide xbuildenv install --nightly

# Install a specific nightly version
pyodide xbuildenv install 20260520 --nightly

# Install the debug variant of the latest nightly release
pyodide xbuildenv install --debug

Listing installed versions#

# List all installed versions (active version marked with *)
pyodide xbuildenv versions

Output:

* 0.29.3
  314.0.0

Switching between versions#

pyodide xbuildenv use 0.29.3

Checking the current version#

pyodide xbuildenv version

Uninstalling#

# Uninstall the current version
pyodide xbuildenv uninstall

# Uninstall a specific version
pyodide xbuildenv uninstall 0.29.3

Searching for available versions#

# Show versions compatible with your Python and pyodide-build
pyodide xbuildenv search

# Show all available versions (including incompatible ones)
pyodide xbuildenv search --all

# Search nightly releases
pyodide xbuildenv search --nightly

# Search nightly debug releases
pyodide xbuildenv search --debug

# Combine flags: show all nightly and debug releases
pyodide xbuildenv search --nightly --debug --all

# Output as JSON (useful for scripting)
pyodide xbuildenv search --json

Where the xbuildenv is stored#

pyodide-build resolves the xbuildenv path in this order:

  1. PYODIDE_XBUILDENV_PATH environment variable

  2. xbuildenv_path in pyproject.toml under [tool.pyodide.build]

  3. Platform cache directory (~/.cache/pyodide on Linux, ~/Library/Caches/pyodide on macOS)

Therefore, to pin a custom location for caching, etc:

export PYODIDE_XBUILDENV_PATH=/path/to/xbuildenv

Or in pyproject.toml:

[tool.pyodide.build]
xbuildenv_path = "/path/to/xbuildenv"

Emscripten SDK#

Each Pyodide version requires a specific Emscripten version. The Emscripten SDK is installed automatically when you run pyodide build. You can also install it manually:

pyodide xbuildenv install-emscripten

Check the required Emscripten version:

pyodide config get emscripten_version

What’s next?#