🦊 ruyiJS

Run any site's JavaScript from Python — with the real Firefox engine.

A new-generation, minimalist browser purpose-built for AI-driven automation. The authentic Firefox JavaScript engine and networking stack, with no window and no renderer — made for web scraping, JS reverse engineering, data collection, and getting past bot checks.

Sponsored by

           

Contributors

      

Install  ·  Features  ·  Verification systems  ·  Examples  ·  FAQ  ·  Contact  ·  LinuxDO  ·  English · 简体中文

⚠️ Disclaimer: This project is for researching next-generation AI browsers. Any form of brute-force reverse engineering is strictly rejected. The source code is open source under the AGPL-3.0; closed-source or proprietary use requires a commercial license.

Is ruyiJS for you?

Headless Chrome and Playwright hand you a whole browser: a GPU-rendering, window-managing, memory-hungry process that anti-bot vendors have spent years learning to detect. ruyiJS takes the opposite path — it embeds only the Firefox internals that matter for automation and leaves the rest behind:

• The real engine, not an impersonation. Genuine SpiderMonkey (Firefox 159) and the Necko network stack execute a site's JavaScript, challenges, signatures, and fingerprints exactly as Firefox would.
• Truly headless. No window, no layout, no renderer. A pure JavaScript + Web API environment that starts fast and stays light.
• Isolated and reproducible. Each Context is its own process with a persistent JavaScript world and its own proxy, so sessions never leak into each other.
• Offline when you need it. Serve scripts and responses yourself and replay a whole captured flow with no network.

If you scrape, reverse-engineer web JavaScript, or collect data behind a challenge, it's for you. If a plain HTTP client already gets your pages, you don't need it.

Wheels for Windows x64, macOS arm64 and Linux x86_64 are on PyPI for Python 3.10+. GitHub Actions builds each of them from the official Firefox 159.0 source (build from source).

📦 Installation

python -m pip install ruyijs

Requirements: 64-bit Python 3.10+ on Windows x64, on macOS 26 or later (Apple Silicon), or on Linux x86_64 with glibc 2.39 or later (Ubuntu 24.04, Debian 13, Fedora 40 and newer).

The Windows wheel ships the SHA256-pinned SpiderMonkey + Necko runtime (~42 MB). Local scripts run offline right after install — no browser download, no external dependencies.

macOS arm64: the macosx_26_0_arm64 wheel loads pages over direct HTTPS through libnecko_core.dylib and libnecko_quic.dylib, linked against the NSS of the same Firefox source. It has no xpcshell. Context(proxy=...) uses an HTTP CONNECT tunnel into libnecko_core when that binary is absent. The Necko helper runs on the Python that installed ruyijs; its packages are dependencies of the macOS wheel. Details and the remaining gaps are in docs/macos.md.

Linux x86_64: the manylinux_2_39_x86_64 wheel is a native ELF build, contributed by @Starktomy in #5. Text uses fontconfig, FreeType and HarfBuzz with the fonts installed on the machine, WebCrypto uses OpenSSL 3, and the Necko helper (NSS 3.131, Neqo for HTTP/3) brings its own Python. See docs/linux.md.

To upgrade:

python -m pip install --upgrade ruyijs

To verify the installation:

import ruyijs
print(ruyijs.__version__)   # 0.3.7

Build from source

git clone --recurse-submodules https://github.com/cutetailbud/ff-ruyijs

The firefox/ submodule is the official Firefox 159.0 release (mozilla-firefox/firefox at FIREFOX_159_0_RELEASE, a shallow clone). The workflows that build the PyPI wheels are the reference for a local build: .github/workflows/wheels.yml runs ci/firefox/build.sh js|browser|toolchain and tools/build.py on Windows and macOS, and the steps of ci/linux/build.sh on Linux.

🚀 Quick start

1 · Open a context and run JavaScript. Variables and functions persist across eval calls within the same context.

from ruyijs import Context

with Context() as context:
    context.eval("let count = 40")
    print(context.eval("count += 2"))        # 42
    print(context.eval("navigator.userAgent"))

3 · Point it at a real target. Configure the environment, load the page, and let the site's own JavaScript mint whatever token it demands.

This is the beginning of the README. Read the rest at the original. Read the full README ↗