Installation

English · 中文

Installation

Requirements

• Windows x64, macOS arm64 (macOS 26 or later) or Linux x86_64 (glibc 2.39 or later: Ubuntu 24.04, Debian 13, Fedora 40 and newer).
• 64-bit Python 3.10 or newer, verified on Python 3.10 – 3.14.
• Nothing else. The wheel brings its own runtime: no browser download, and no third-party Python dependencies on Windows.

Each platform has its own wheel on PyPI and pip picks the right one. Platform notes are under macOS arm64 and Linux x86_64 below.

Install

python -m pip install ruyijs

Upgrade

python -m pip install --upgrade ruyijs

Verify

import ruyijs
print(ruyijs.__version__)          # 0.3.0
print(ruyijs.get_runtime_path())   # runtime root that contains dist/ and vendor/

Then run one line of JavaScript:

from ruyijs import Context

with Context() as context:
    print(context.eval("navigator.userAgent"))   # a Firefox user agent

With a clone of the repository you can also run the offline smoke test that CI runs against an installed wheel. It checks evaluation, value conversion, JS exceptions, page loading with offline resources, the event loop and the Firefox identity the engine reports, and ends with all smoke checks passed:

python ci/smoke_test.py

What the wheel bundles

The Windows wheel ships a SHA256-pinned runtime of about 42 MB:

• js.exe — the SpiderMonkey shell (Firefox 159) linked with the ruyiJS browser environment, plus its runtime libraries;
• Necko — Firefox's network stack (HTTP/1.1, HTTP/2, HTTP/3, with TLS done by NSS);
• the embedded CPython and the Python packages the Necko helper uses (listed in NOTICE).

Local scripts run offline right after installation. The pinned archive — its name, size, SHA-256, the shell and inventory hashes, and the release URL — is recorded in runtime.json. When setup.py builds a wheel, tools/wheel_runtime.py downloads that archive and verifies it against runtime.json.

How the runtime is found

Context and get_runtime_path() never download anything. The shell is chosen in this order:

1. Context(shell=...), if given;
2. the RUYIJS_SHELL environment variable — the path of an existing js.exe (js on macOS and Linux); the runtime root is two levels above it;
3. dist/js.exe in a source checkout, when the package is imported from the repository's python/ folder;
4. the runtime bundled in the installed package (ruyijs/_runtime).

If none exists, a FileNotFoundError lists the paths that were searched.

Using a source checkout without compiling

GitHub releases carry the prebuilt runtime as ruyijs-runtime-<version>-win-amd64.zip (dist/js.exe, runtime libraries, Necko). Unzip it and either set RUYIJS_SHELL=<unzip-dir>\dist\js.exe, or place it at the repository root so that dist/js.exe and vendor/necko-derived exist; python/ruyijs then finds it. To compile js.exe yourself, see Build from Source.

macOS arm64

Since 0.3.0 PyPI carries a macosx_26_0_arm64 wheel (macOS 26 or later), built by GitHub Actions from the firefox/ submodule. Pages load over direct HTTPS through libnecko_core.dylib and libnecko_quic.dylib. The wheel has no xpcshell, so Context(proxy=...) is not available on macOS yet.

The Necko helper runs on the interpreter that installed ruyijs, so the macOS wheel depends on requests, brotli, zstandard, h2, cryptography, publicsuffixlist and, before Python 3.14, backports.zstd. The maintainer build with an xpcshell donor, and what was verified on macOS, are in docs/macos.md.

Linux x86_64

Since 0.3.0 PyPI carries a manylinux_2_39_x86_64 wheel (glibc 2.39 or later), contributed by @Starktomy in #5. It bundles the libraries it links except glibc, and a private Python 3.14 for the Necko helper (NSS 3.131, Neqo for HTTP/3). Text is drawn with the fonts installed on the machine through fontconfig, so canvas text differs from Windows unless the same fonts are present. See docs/linux.md.

On any other platform get_runtime_path() raises OSError: ruyijs requires Windows x64, macOS arm64 or Linux x86_64.

---

Next: Quick Start