CLI Reference

All commands are accessed through the pyodide CLI, provided by the pyodide-cli package (installed automatically with pyodide-build).

pyodide build

Use pypa/build to build a Python package from source, pypi or url.

Arguments:

SOURCE_LOCATION: Build source, can be source folder, pypi version specification,

or url to a source dist archive or wheel file. If this is blank, it

will build the current directory.

Usage

pyodide build [OPTIONS] [SOURCE_LOCATION]

Options

-o, --outdir <output_directory>

which directory should the output be placed into?

-r, --requirements <requirements_txt>

Build a list of package requirements from a requirements.txt file

--exports <exports>

Which symbols to export when linking .so files. Choices: ‘pyinit’ (only PyInit_<module>), ‘requested’ (default, symbols requested by the build system), ‘whole_archive’ (all symbols from all archives), or a comma-separated list of symbol names.

--build-dependencies, --no-build-dependencies

Fetch dependencies from pypi and build them too.

--output-lockfile <output_lockfile>

Output list of resolved dependencies to a file in requirements.txt format

--skip-dependency <skip_dependency>

Skip building or resolving a single dependency, or a pyodide-lock.json file. Use multiple times or provide a comma separated list to skip multiple dependencies.

--skip-built-in-packages, --no-skip-built-in-packages

Don’t build dependencies that are built into the pyodide distribution.

--compression-level <compression_level>

Compression level to use for the created zip file

Default:

6

-n, --no-isolation

Disable building the project in an isolated virtual environment. Build dependencies must be installed separately when this option is used

-x, --skip-dependency-check

Do not check that the build dependencies are installed. This option is only useful when used with –no-isolation.

-C, --config-setting <KEY[=VALUE>

Settings to pass to the backend. Works same as the –config-setting option of pypa/build.

--xbuildenv-path <xbuildenv_path>

Path to the cross-build environment directory (default: resolved from config or platformdirs cache).

--skip-emscripten-install

Skip automatic installation of Emscripten if not found.

-v, --verbose

Increase build verbosity. Use -v for verbose output, -vv for very verbose output.

Arguments

SOURCE_LOCATION

Optional argument

Environment variables

PYODIDE_BUILD_EXPORTS

Provide a default for --exports

PYODIDE_XBUILDENV_PATH

Provide a default for --xbuildenv-path

PYODIDE_SKIP_EMSCRIPTEN_INSTALL

Provide a default for --skip-emscripten-install

pyodide clean

Clean build artifacts.

Usage

pyodide clean [OPTIONS] COMMAND [ARGS]...

recipes

Remove build artifacts for recipe packages.

Arguments:

TARGETS: Packages or tags (tag:<name>) to clean. Defaults to all packages.

Usage

pyodide clean recipes [OPTIONS] [TARGETS]...

Options

--recipe-dir <recipe_dir>

Directory containing package recipes. Defaults to <pyodide root>/packages.

--build-dir <build_dir>

Directory where package build artifacts are stored. Defaults to recipe directory.

Arguments

TARGETS

Optional argument(s)

Environment variables

PYODIDE_RECIPE_BUILD_DIR

Provide a default for --build-dir

pyodide config

Manage config variables used in pyodide.

Usage

pyodide config [OPTIONS] COMMAND [ARGS]...

get

Get a value of a single config variable used in pyodide.

Arguments:

CONFIG_VAR: A config variable to get. Use list to see all possible values.

Usage

pyodide config get [OPTIONS] CONFIG_VAR

Arguments

CONFIG_VAR

Required argument

list

List config variables used in pyodide.

Usage

pyodide config list [OPTIONS]

pyodide py-compile

Compile .py files to .pyc in a wheel, a zip file, or a folder with wheels or zip files.

If the provided folder contains the pyodide-lock.json file, it will be rewritten with the updated wheel / zip file paths and sha256 checksums.

Arguments:

PATH: Path to the input wheel or a folder with wheels or zip files.

Usage

pyodide py-compile [OPTIONS] PATH

Options

--silent, --no-silent

Silent mode, do not print anything.

--keep, --no-keep

Keep the original wheel / zip file.

--compression-level <compression_level>

Compression level to use for the created zip file.

Default:

6

--exclude <exclude>

List of files to exclude from compilation, works only for directories. Defaults to no files.

Arguments

PATH

Required argument

pyodide venv

Create a Pyodide virtual environment.

Additionally, this interface supports a subset of the arguments that virtualenv supports, with some minor differences for Pyodide compatibility. Please note that passing extra options is experimental and may be subject to change.

Arguments:

DEST: directory to create virtualenv at

Usage

pyodide venv [OPTIONS] DEST

Options

--clear, --no-clear

Remove the destination directory if it exists.

--no-vcs-ignore

Don’t create VCS ignore directive in the destination directory.

--no-download, --never-download

Disable download of the latest pip/setuptools from PyPI.

--download

Enable download of the latest pip/setuptools from PyPI.

--extra-search-dir <extra_search_dir>

A path containing wheels to extend the internal wheel list.

--pip <pip>

Version of pip to install as seed: embed, bundle, or exact version.

Default:

'bundle'

--setuptools <setuptools>

Version of setuptools to install as seed: embed, bundle, none or exact version.

--no-setuptools

Do not install setuptools.

--no-periodic-update

Disable the periodic update of the embedded wheels.

Arguments

DEST

Required argument

pyodide xbuildenv

Manage cross-build environment for building packages for Pyodide.

Usage

pyodide xbuildenv [OPTIONS] COMMAND [ARGS]...

install

Install cross-build environment.

The installed environment is the same as the one that would result from PYODIDE_PACKAGES=’scipy’ make except that it is much faster. The goal is to enable out-of-tree builds for binary packages that depend on numpy or scipy.

Arguments:

VERSION: version of cross-build environment to install (optional)

Usage

pyodide xbuildenv install [OPTIONS] [VERSION]

Options

--path <path>

destination to download cross-build environment directory to (default: resolved from config or platformdirs cache).

--url <url>

URL to download cross-build environment from.

-f, --force

force installation even if the version is not compatible.

--nightly

install a nightly cross-build environment instead of a stable release.

--debug

install the debug variant of the cross-build environment. Combine with –nightly to install the nightly debug variant.

--skip-cross-build-packages

Deprecated, no-op. Cross-build packages are installed lazily when required by build dependencies.

Arguments

VERSION

Optional argument

Environment variables

PYODIDE_XBUILDENV_PATH

Provide a default for --path

PYODIDE_SKIP_CROSS_BUILD_PACKAGES

Provide a default for --skip-cross-build-packages

install-emscripten

Install Emscripten SDK into the cross-build environment.

This command clones the emsdk repository, installs and activates the specified Emscripten version, and applies Pyodide-specific patches.

If the requested version is already installed, the command is a no-op unless –force is passed.

Usage

pyodide xbuildenv install-emscripten [OPTIONS]

Options

--version <version>

Emscripten version corresponding to the target Pyodide version

--path <path>

Pyodide cross-env path

-f, --force

force reinstallation even if the same version is already installed.

search

Search for available versions of cross-build environment.

Usage

pyodide xbuildenv search [OPTIONS]

Options

--metadata <metadata_path>

path to cross-build environment metadata file. It can be a URL or a local file. If not given, the default metadata file is used.

-a, --all

search all versions, without filtering out incompatible ones.

--nightly

search nightly releases instead of stable ones.

--debug

search debug releases. Searches stable-debug by default. Combine with –nightly to search nightly-debug releases.

--json

output results in JSON format.

uninstall

Uninstall cross-build environment.

Arguments:

VERSION: version of cross-build environment to uninstall (optional)

Usage

pyodide xbuildenv uninstall [OPTIONS] [VERSION]

Options

--path <path>

path to cross-build environment directory.

Arguments

VERSION

Optional argument

use

Select a version of cross-build environment to use.

Arguments:

VERSION: version of cross-build environment to use (required)

Usage

pyodide xbuildenv use [OPTIONS] VERSION

Options

--path <path>

path to cross-build environment directory.

Arguments

VERSION

Required argument

version

Print current version of cross-build environment.

Usage

pyodide xbuildenv version [OPTIONS]

Options

--path <path>

path to cross-build environment directory.

versions

Print all installed versions of cross-build environment.

Usage

pyodide xbuildenv versions [OPTIONS]

Options

--path <path>

path to cross-build environment directory.

Export modes

The --exports option to pyodide build controls which symbols are exported when linking .so files.

Mode	Description
pyinit	Export only the PyInit_<module> symbol. Minimises output size; use when no other extension needs to call into this one at the C level.
requested (default)	Export symbols explicitly requested by the build system (e.g. via EXPORTED_FUNCTIONS). Balances size and compatibility.
whole_archive	Export every symbol from every linked archive. Use when other extensions need to call into this one at the C level.

You can also pass a comma-separated list of symbol names to export specific symbols, for example: --exports PyInit__core,helper_fn.