Customizing Compiler Flags

Customizing Compiler Flags#

pyodide-build sets default compiler and linker flags required/optimized for WebAssembly modules. You can inspect, override, and extend these flags for your build.

Default flags#

You can inspect the default values we use by running:

pyodide config get cflags
pyodide config get cxxflags
pyodide config get ldflags

Note that the default flag differs per Pyodide version you target.

Overriding flags#

You can override flags in multiple ways:

via pyproject.toml#

[tool.pyodide.build]
cflags = "-O2 -g2"
cxxflags = "-O2 -g2"
ldflags = "-O2 -g2"

via environment variables#

Set environment variables before running pyodide build:

export CFLAGS="$(pyodide config get cflags) -DMY_DEFINE=1"
pyodide build .

Environment variables take precedence over pyproject.toml settings.

Configuration precedence#

Flags are resolved in this order (highest priority first):

  1. Environment variables

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

  3. Cross-build environment defaults

Flags that are automatically filtered#

pyodide-build’s compiler wrapper silently removes flags that are incompatible with Emscripten/WebAssembly — you don’t need to remove them from your build scripts. See the Configuration Reference for the full list.

Rust flags#

Rust compiler flags are configured separately:

pyodide config get rustflags
# e.g., -C link-arg=-sSIDE_MODULE=2 -C link-arg=-sWASM_BIGINT

Override in pyproject.toml:

[tool.pyodide.build]
rustflags = "-C link-arg=-sSIDE_MODULE=2 -C link-arg=-sWASM_BIGINT -C opt-level=2"

What’s next?#