Configuration Reference

pyodide-build reads configuration from multiple sources. This page documents all available settings.

Precedence

Configuration is resolved in this order (highest priority first):

1. Environment variables

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

3. Cross-build environment defaults

4. Built-in defaults

pyproject.toml

Add configuration under [tool.pyodide.build]:

[tool.pyodide.build]
cflags = "-O2"
cxxflags = "-O2"
ldflags = "-s SIDE_MODULE=1 -O2"
xbuildenv_path = "/path/to/xbuildenv"

User-overridable settings

These keys can be set in pyproject.toml under [tool.pyodide.build] or via environment variables:

pyproject.toml key	Env variable	Description
cflags	SIDE_MODULE_CFLAGS	C compiler flags
cxxflags	SIDE_MODULE_CXXFLAGS	C++ compiler flags
ldflags	SIDE_MODULE_LDFLAGS	Linker flags
rustflags	RUSTFLAGS	Rust compiler flags
rust_toolchain	RUST_TOOLCHAIN	Required Rust nightly toolchain
rust_emscripten_target_url	RUST_EMSCRIPTEN_TARGET_URL	URL for the Rust Emscripten target
meson_cross_file	MESON_CROSS_FILE	Path to the Meson cross file
xbuildenv_path	PYODIDE_XBUILDENV_PATH	Path to the cross-build environment
ignored_build_requirements	IGNORED_BUILD_REQUIREMENTS	Space-separated PEP 508 build requirements to ignore
skip_emscripten_version_check	SKIP_EMSCRIPTEN_VERSION_CHECK	Skip Emscripten version compatibility check (0/1)
build_dependency_index_url	BUILD_DEPENDENCY_INDEX_URL	PyPI index URL for host-side build dependencies
default_cross_build_env_url	DEFAULT_CROSS_BUILD_ENV_URL	URL override for the cross-build environment archive
use_legacy_platform	USE_LEGACY_PLATFORM	Use the legacy pyodide_* platform tag instead of pyemscripten_* (0/1)

Run pyodide config list to see all available variables and their current values.

Environment variables

Querying configuration

Use pyodide config to inspect active values:

# List all settings
pyodide config list

# Get a specific value
pyodide config get cflags
pyodide config get meson_cross_file
pyodide config get rust_toolchain

See the CLI Reference for details.