Run HARK in the browser (Pyodide / JupyterLite): make numba optional

[alanlujan91]

Correction (2026-08-11): the claim below that numba cannot run in a browser is out of date. numba now builds for emscripten-wasm32 via emscripten-forge and works under JupyterLite. See this comment for what still holds and what changes. The Phase 1 shim is still worth doing; its justification is different.

Goal

Make HARK importable and usable in the browser: Pyodide, JupyterLite, and anything else running CPython on WebAssembly. The target is that a student or referee can open a notebook link and run a HARK model with no local install.

This issue enumerates the specific changes required. Findings below were measured against main at e7909203, not assumed.

The blocker is numba, and today it is total

HARK.core imports numba transitively, so HARK does not merely run slowly in Pyodide. It does not import at all.

import HARK.core   ->  ImportError: No module named 'numba'

Three modules put it on the core path:

Module	How numba enters
HARK/utilities.py	import numba
HARK/simulator.py	from numba import njit
HARK/SSJutils.py	from numba import njit

numba cannot be fixed upstream on any useful timescale. It requires llvmlite, which requires LLVM itself compiled to WebAssembly. The Pyodide request has been open since 2020 (pyodide/pyodide#621), the one attempt to build it was closed (pyodide/pyodide#618), and numba's own WASM-target issue (numba/numba#3284) is unshipped. This is not something to wait for.

The same is true of JAX, for a different reason: jaxlib is a native XLA binary with no WebAssembly build. Any accelerator that ships compiled artifacts is out. What does work in Pyodide is NumPy, SciPy, pandas, matplotlib, xarray and the rest of the standard scientific stack, which means vectorized NumPy is the accelerator available in the browser.

What we are lucky about

The dependency situation is much better than it looks:

• HARK uses exactly two numba APIs: njit (54 sites) and prange (3 sites). There is no typed.List, no guvectorize, no vectorize, and no numba.types objects. cache=True (33 sites) and parallel=True are kwargs that a fallback can ignore.
• interpolation (econforge) and quantecon both pull numba, but neither is on the core import path. They are confined to econforgeinterp.py, dcegm.py, and ConsIndShockModelFast.py.
• joblib and xarray are on the core path and both work in Pyodide.

So the core path has one blocker, not a web of them.

Phase 1: make numba optional so HARK imports

Add a single compatibility module, HARK/_numba.py, holding a guarded import with a no-op fallback:

try:
    from numba import njit, prange
    HAS_NUMBA = True
except ImportError:
    HAS_NUMBA = False
    prange = range

    def njit(*args, **kwargs):
        if len(args) == 1 and callable(args[0]) and not kwargs:
            return args[0]          # bare @njit
        return lambda func: func    # @njit(...) and @njit("sig", cache=True)

njit is three calling conventions under one name (decorator, decorator factory, factory with a positional signature string), so the callable(args[0]) and not kwargs guard is load-bearing. A naive def njit(f): return f silently breaks @njit(cache=True) by returning True as the function. This prototype has been verified against all four forms HARK uses, with numba absent: bare, cache=True, njit("float64(float64[:])", cache=True), and parallel=True with prange.

prange = range is a correct fallback. numba's prange is range plus a parallelism hint, and the loops in question are order independent, so serial execution is correct and only slower.

Then change the eight importing modules to import from HARK._numba instead of numba:

File	@njit	prange / parallel	explicit sigs
HARK/ConsumptionSaving/ConsIndShockModelFast.py	14	4	0
HARK/numba_tools.py	10	0	0
HARK/mat_methods.py	8	0	0
HARK/simulator.py	8	0	0
HARK/SSJutils.py	4	0	0
HARK/utilities.py	4	5	0
HARK/dcegm.py	3	0	2
HARK/interpolation.py	3	0	0

Finally, move numba out of requirements/base.txt into an extra, so a default install is browser compatible and pip install econ-ark[fast] restores compiled speed.

This phase is mechanical and changes no numerical behavior when numba is present.

Phase 2: prove the fallback in CI, or it will rot

With numba installed, CI never executes the fallback path. A numba-only semantic (integer overflow, division behavior, or a loop that is only correct because it was compiled) can diverge silently and nobody finds out until a browser user does.

Add one CI job that installs without the fast extra and runs the suite with numba absent. This is the difference between numba being genuinely optional and being nominally optional.

Phase 3: decide what "usable in the browser" means

Phase 1 makes HARK import and produce correct answers. It does not make it fast. Every @njit path becomes interpreted Python, and the two parallel=True loops in HARK/utilities.py iterate over dist_mGrid x dist_pGrid, which in pure Python is likely minutes rather than seconds.

Two defensible targets, and they cost very different amounts:

1. Importable and usable for teaching-scale models. Phase 1 plus Phase 2 gets this. Small AgentCount, short T_sim, coarse grids. Good enough for a course notebook or a referee reproducing a figure.
2. Performant in the browser. Requires rewriting the hot loops as vectorized NumPy, which Pyodide runs at native-ish speed. This is real work and should be scoped from measurement, not guesswork: profile the pure-Python path first, then rewrite only what dominates. The utilities.py prange loops are the obvious first candidates.

Vectorized NumPy is worth preferring over numba even outside the browser, since it removes a compiled dependency from the hot path entirely.

Phase 4: the three modules that stay unavailable

econforgeinterp.py, dcegm.py, and ConsIndShockModelFast.py import interpolation and quantecon, both of which pull numba themselves. Making HARK's own numba use optional does not help these, because the dependency is external.

Options, in rough order of appeal:

• Leave them unavailable in the browser and raise a clear error on import. Core HARK still works, and these are specialist modules.
• Replace interpolation.interp with a NumPy or SciPy equivalent where the call is simple enough. dcegm.py uses only interp.
• ConsIndShockModelFast.py is the numba-accelerated variant of a model that already has a pure-Python implementation, so the browser can simply use the non-Fast path.

quantecon.optimize.newton_secant in ConsIndShockModelFast.py is a single scalar root finder and has a straightforward SciPy replacement if that module is ever wanted in the browser.

Phase 5: parallelism

HARK/core.py and HARK/estimation.py use joblib.Parallel. joblib imports fine under Pyodide but there are no worker processes in a browser tab, so n_jobs must resolve to 1. Confirm this degrades gracefully rather than hanging or raising.

Non-goals

• Getting numba or JAX to run in the browser. Neither is achievable, and this issue does not depend on either.
• Removing numba as an option for local use. It stays, as an extra, and remains the fast path off the browser.
• Adding JAX. Separate discussion, and it has the same WebAssembly problem, so it would work against this goal.

Open questions

1. Which of the two Phase 3 targets are we buying? That decides whether this is a small change or a sustained vectorization effort.
2. Should the default install be browser compatible (numba in an extra) or should the browser build be the special case (numba stays in base, browser installs a subset)? Putting numba in an extra makes the browser path the default and is the stronger statement, but it changes what pip install econ-ark gives existing users.
3. Do we want a pinned JupyterLite deployment in CI so browser compatibility is continuously tested rather than asserted?

Verification notes

Everything above was measured on main at e7909203:

• numba absence was simulated with a sys.meta_path finder that raises on numba*, with a rejection test confirming the blocker actually blocks. An earlier attempt using the legacy find_module protocol silently did nothing on Python 3.13 and produced a false pass.
• API usage counts come from a grep sweep across HARK/.
• Core-path membership was determined by importing HARK.core and inspecting sys.modules.

[llorracc]

@alanlujan91 This is a terrific writeup — measured exactly where it needed to be. Answers to your three open questions, starting from the general principle:

The default should be regular numba. Browser-compatibility should be something a particular notebook or codebase can choose as its default — and that choice should be easy to make (a documented one-liner: the lite/deps=False install path, or whatever mechanism you prefer) — rather than something imposed on every pip install econ-ark. The caveat that comes with that position: if the browser path is opt-in, we should add the CI that actually exercises it, so it stays real rather than asserted.

1. Target: importable and teaching-usable. Phase 1 + Phase 2 is what we're buying now — small AgentCount, coarse grids, a course notebook or a referee reproducing a figure. Vectorizing hot loops beyond that should be selective and measurement-driven, as you say — not a blanket goal. And the power-user features (the numba fast path, JAX compatibility where it exists) stay available as options on some but not all parts of the codebase: the parts where they pay for themselves. Nothing about the browser target should subtract capability from the research configuration.

2. Keep numba in base. pip install econ-ark should keep giving existing users what it gives them today. The browser install is the special case, and it's fine for it to be a special case — an explicit, documented, easy choice — rather than the default that changes everyone else's install.

3. Yes — a pinned JupyterLite deployment in CI is a great idea. That's the same point as the caveat above: continuously tested, not asserted. It also pairs naturally with your Phase-2 numba-absent suite job.

[alanlujan91]

Correction: numba now runs in the browser, so the premise above is out of date

The section "The blocker is numba, and today it is total" claimed numba could not be fixed upstream on any useful timescale, citing pyodide/pyodide#621 (open since 2020), pyodide/pyodide#618 (closed), and numba/numba#3284 (unshipped).

That was accurate for stock Pyodide and is no longer the whole picture. QuantStack shipped numba for emscripten-wasm32 through emscripten-forge, announced 2026-08-11: https://notebook.link/blog/numba-in-the-browser/

Verified against emscripten-forge/recipes rather than the blog post alone:

PR	merged
#5934	2026-07-17	llvmlite 0.48.0 recipe with a WASM execution engine
#6133	2026-08-05	Add Numba
#6135, #6136	2026-08-05	PyTensor's numba backend on WebAssembly
#6185	2026-08-06	Fix numba array slice assignment on wasm32
#6208, #6234	2026-08-10, 2026-08-11	Persistent numba cache across JupyterLite kernels
#6235, #6237	2026-08-11	Isolate embedded LLVM symbols; unpin llvmlite

llvm, llvmlite, and numba recipes are all present. The approach is real JIT compilation, not emulation: numba lowers to LLVM IR through llvmlite, that compiles to a WASM object, and wasm-ld runs in-process to link it as a side module, because a browser cannot spawn a linker subprocess and cannot allocate executable memory the way a native LLVM JIT expects.

What this changes

There are two browser targets, not one, and they differ in what they can run.

JupyterLite with emscripten-forge (xeus-python). numba works. HARK's njit and prange sites keep their compiled performance. If the goal is a student or referee opening a notebook link, this is the better target, and it may need no HARK changes at all beyond packaging.

Stock Pyodide. numba is still absent, because emscripten-forge is a separate conda channel rather than Pyodide's package set. Anything loading HARK through pyodide.loadPackage or PyScript still hits the import failure documented above.

What this does not change

The HARK/_numba.py shim in Phase 1 is still worth doing, for reasons that no longer depend on numba being permanently unavailable:

1. Stock Pyodide, PyScript, and any minimal install still need it.
2. It is about 12 lines with a default-off blast radius, and it makes import HARK.core succeed anywhere.
3. emscripten-forge numba is days old. PRs were still landing on the day of the announcement, and the authors describe the work as establishing the architecture with more to do. Depending on it as the only path is premature.

So Phase 1 stands, with its justification changed from "numba can never work in a browser" to "numba works on one browser target and not the other, and the shim covers the gap."

JAX is unaffected

There is no jax or jaxlib recipe in emscripten-forge and no PR proposing one. jaxlib is a native XLA binary with no WebAssembly build, so the original reasoning holds without qualification. The gap between the two has widened rather than closed: numba acquired a browser story this month, JAX did not.

Next step

Before committing to the Phase 1 through Phase 3 plan, someone should test whether HARK imports and solves under JupyterLite with emscripten-forge numba as it stands today. If it does, the sequencing changes: packaging HARK for that channel becomes the fast path to a working browser demo, and the shim becomes a portability improvement to land on its own schedule rather than a prerequisite.

[llorracc]

@alanlujan91 This is great news — the best possible resolution: numba stays in base and the browser still gets compiled speed on the JupyterLite target. Thanks for chasing down the correction and verifying it against the recipes rather than the announcement.

[anutosh491]

Hi,

Author of the blog mentioned here :)

Feel free to reach out to the me or the emscripten-forge team at QuantStack in case you would like help with some of the packaging work here @SylvainCorlay @MMesch !

[llorracc]

@anutosh491 This is great news — thank you for the remarkable work getting numba onto emscripten-wasm32, and for the generous offer of help. @alanlujan91 is driving the browser effort on our side; I expect we will gladly take you and the emscripten-forge team up on it as the packaging work takes shape.

[anutosh491]

Sure. We would love to have HARK on emscripten-forge too.

I would also like to try compiling jax jit for wasm just like we did with numba. if that's a backend HARK would like to have, you can consider funding us for the work and we can collaborate on it :)