`jupyterlite-pyodide-lock`#

The features of jupyterlite-pyodide-lock are be configured along with other JupyterLite features in a site’s jupyter_lite_config.json.

Addons#

The PyodideLockAddon provides the main tasks for working with lockfile requirements.

PyodideLockAddon¶

See full PyodideLockAddon API

name	help	type	[items]	default
`bootstrap_wheels`	packages names from the lockfile (or `.whl` URLs or local paths) to load before the solve, such as a custom `micropip`	array	string	`["micropip", "packaging"]`
`constraints`	PEP-508 specifications that constrain the bootstrap solve. Requires `micropip >=0.9.0`.	array	string	`[]`
`enabled`	whether 'pyodide-lock' integration is enabled	boolean		`false`
`extra_preload_packages`	extra packages to add to `PyodideAddon.loadPyodideOptions.packages`. These will be downloaded at kernel startup, and installed, but not imported to `sys.modules`	array	string	`[]`
`lock_date_epoch`	a UNIX epoch timestamp: packages modified after this time will be removed from proxied JSON responses	number		`0`
`locker`	approach to use for running `pyodide` and solving the lock: these will have further configuration options under the same-named configurable	string	`BrowserLocker` `WebDriverLocker`	`"BrowserLocker"`
`packages`	URLs of packages, or local (folders of) compatible wheels for `pyodide` dependencies	array	string	`[]`
`preload_packages`	`pyodide_kernel` dependencies to add to `PyodideAddon.loadPyodideOptions.packages`. These will be downloaded and installed, but not imported to `sys.modules`	array	string	`["ssl", "sqlite3", "ipykernel", "comm", "pyodide_kernel", "ipython"]`
`specs`	PEP-508 specifications for `pyodide` dependencies	array	string	`[]`

The PyodideLockOfflineAddon provides optional fetching and pruning of a subset of packages in a pyodide distribution, including any required local packages and their dependencies.

PyodideLockOfflineAddon¶

See full PyodideLockOfflineAddon API

name	help	type	[items]	default
`enabled`	whether 'pyodide-lock' integration is enabled	boolean		`false`
`excludes`	regular expressions to exclude from downloading	array	string	`[]`
`extra_excludes`	more regular expressions to exclude from downloading	array	string	`[]`
`extra_includes`	more regular expressions for package names to download for offline usage	array	string	`[]`
`includes`	regular expressions for package names to download for offline usage	array	string	`[]`
`prune`	prune packages not requested to be offline	boolean		`false`

Lockers#

The BaseLocker subclasses provides a browser with a minimal pyodide environment (not JupyterLite) in which to run micropip.freeze.

🧩 Locker Plugins

Optional lockers are provided by other jupyterlite-pyodide-lock- packages

BrowserLocker¶

See full BrowserLocker API

name	help	type	[items]	default
`browser`	an alias for a pre-configured browser	string		`""`
`browser_argv`	the non-URL arguments for the browser process: if configured, ignore 'browser', 'headless', 'private_mode', 'temp_profile', and 'profile'	array	string	`[]`
`extra_browser_argv`	additional non-URL arguments for the browser process.	array	string	`[]`
`extra_micropip_args`	options for 'micropip.install'	object		`{}`
`headless`	run the browser in headless mode	boolean		`true`
`host`	the host on which to bind	string		`"127.0.0.1"`
`port`	the port on which to listen	number		`0`
`private_mode`	run the browser in private mode	boolean		`true`
`profile`	run the browser with a copy of the given profile directory	string		`null`
`protocol`	the protocol to serve	string		`"http"`
`pyodide_cdn_url`	remote URL for the version of a full pyodide distribution	string		`"https://cdn.jsdelivr.net/pyodide/v0.27.6/full"`
`pypi_api_url`	remote URL for a Warehouse-compatible JSON API	string		`"https://pypi.org/pypi"`
`temp_profile`	run the browser with a temporary profile: clobbered by `profile`	boolean		`true`
`timeout`	seconds to wait for a solve	number		`0`
`tornado_settings`	override settings used by the tornado server	object		`{}`

Appendices#

Chromium CI#

In some continuous integration settings such as GitHub Actions, chromium-like browsers may fail for mysterious reasons.

Chromium Logs#

A first step is gathering better logs:

{
  "BrowserLocker": {
    "extra_browser_argv": ["--enable-logging=stderr", "--v=1"]
  }
}

This generates an enormous amount of output, but will help at least find what to search for in the thousands of chromium flags.

Chromium in Containers#

Some container-based builds are fixed by:

{
  "BrowserLocker": {
    "extra_browser_argv": ["--disable-dev-shm-usage", "--disable-gpu"]
  }
}

Chromium Sandbox#

A (sometimes unavoidable) step is to disable the browser sandbox altogether:

{
  "BrowserLocker": {
    "extra_browser_argv": ["--no-sandbox"]
  }
}

jupyterlite-pyodide-lock#