mini-racer

library0.14.1pypypi✓ verified 22d ago

Mini Racer is a minimal, modern embedded V8 JavaScript engine for Python. It allows executing JavaScript code directly within Python applications. As of version 0.14.1, it provides a stable API for evaluating JS, calling functions, and managing execution contexts. The project has a relatively frequent release cadence, with minor updates and bug fixes appearing every few weeks or months.

serialization

pip install mini-racer

github ↗package ↗

INSTALL

IMPORT

SIG · MINI-RACER

mini-racer

serializationpythonv0.14.1

Install

2.0s avg

Import

259ms

Disk

90MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.14.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.276s · 99MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.0s · import 0.242s · 99MB

90MB installed

● package 90MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MiniRacer

✓ from py_mini_racer import MiniRacer

✗ import py_mini_racer; mr = py_mini_racer.MiniRacer()

Since v0.12.0, the `MiniRacer` class is directly importable from the `py_mini_racer` module. Previously, it was accessed as `py_mini_racer.MiniRacer`.

MiniRacerEvalError

✓ from py_mini_racer import MiniRacerEvalError

Used for catching JavaScript execution errors.

This quickstart demonstrates how to initialize a `MiniRacer` context, evaluate JavaScript code, call a JavaScript function with Python arguments, and handle JavaScript execution errors using `MiniRacerEvalError`.

from py_mini_racer import MiniRacer, MiniRacerEvalError # Initialize a MiniRacer context mr = MiniRacer() # Evaluate JavaScript code to define a function mr.eval("function add(a, b) { return a + b; }") # Call the JavaScript function with Python arguments result = mr.call("add", 1, 2) print(f"Result of add(1, 2): {result}") # Evaluate a simple expression (e.g., getting V8 version) js_version = mr.eval("process.versions.v8") print(f"V8 version: {js_version}") # Demonstrate error handling try: mr.eval("throw new Error('Something went wrong!');") excep MiniRacerEvalError as e: print(f"Caught MiniRacerEvalError: {e}")

Debug

Known issues

breakingThe import path for `MiniRacer` changed significantly. Direct class import `from py_mini_racer import MiniRacer` is now required.

fix

Update your import statements from `import py_mini_racer; mr = py_mini_racer.MiniRacer()` to `from py_mini_racer import MiniRacer; mr = MiniRacer()`.

affects: >=0.12.0

breakingJavaScript errors no longer propagate as generic Python exceptions but raise a specific `MiniRacerEvalError`.

fix

Wrap your `mr.eval()` and `mr.call()` calls in `try...except MiniRacerEvalError` blocks to catch and handle JS errors correctly.

affects: >=0.12.0

breakingThe `v8_args` parameter was removed from the `MiniRacer` constructor.

fix

Remove the `v8_args` parameter when initializing `MiniRacer`. Custom V8 arguments are no longer directly configurable via the constructor.

affects: >=0.13.0

breakingThe `timeout` parameter was removed from the `MiniRacer` constructor. While it was briefly available in v0.12.x, it was removed from the constructor in v0.13.0.

fix

Do not pass a `timeout` argument to the `MiniRacer` constructor. The `timeout` parameter remains available for the `eval()` and `call()` methods for per-operation timeouts.

affects: >=0.13.0

gotchaA `MiniRacer` instance is NOT thread-safe. Accessing a single instance from multiple threads concurrently can lead to crashes or undefined behavior.

fix

Instantiate a separate `MiniRacer` object for each thread that needs to execute JavaScript code. Alternatively, use a thread-safe mechanism like a queue or a lock to serialize access to a single instance.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'py_mini_racer'

The Python package on PyPI is named `mini-racer`, but the primary module it exposes for import is `py_mini_racer`.

fix

Ensure you have installed the correct package with `pip install mini-racer` and then import it using `from py_mini_racer import MiniRacer`.

ERROR: Failed building wheel for mini-racer

The `mini-racer` library requires compiling a C++ V8 engine, which fails if the necessary C++ build tools (like a C++ compiler, Python development headers, or platform-specific tools such as Xcode Command Line Tools on macOS) are not installed or configured correctly for your system.

fix

Install the required C++ build tools for your operating system (e.g., `xcode-select --install` on macOS, Build Tools for Visual Studio on Windows, `build-essential` on Debian/Ubuntu). Additionally, ensure `pip` is updated to allow for downloading pre-compiled wheels if available: `pip install --upgrade pip`.

MiniRacer.JSEvalException: TypeError: Converting circular structure to JSON

This error occurs when you attempt to return a JavaScript object from `mini-racer` that contains circular references or other non-JSON-serializable types, and the library implicitly tries to serialize it to JSON for transfer back to Python.

fix

Modify your JavaScript code to ensure that any values returned to Python are strictly JSON-serializable. For complex objects, explicitly serialize them to a string within JavaScript using `JSON.stringify()` before returning.

UnicodeDecodeError: 'utf-8' codec can't decode byte 0x... in position ...: invalid start byte

This common Python error arises when `mini-racer` attempts to process or return JavaScript strings containing characters that are not correctly encoded (e.g., malformed UTF-8 sequences), leading to a decoding failure when Python tries to interpret the byte stream.

fix

Ensure all JavaScript code and string inputs are consistently encoded, preferably in UTF-8. While `mini-racer` is designed to handle Unicode, verify your environment's locale settings support UTF-8, and if persistent issues arise, explicitly handle encoding and decoding within your Python application.

Upgrade

Version history

0.14.1latest on PyPI · released Feb 1, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

3 hits · last 30 days

node

Resources

githubhttps://github.com/bpcreech/PyMiniRacer ↗

packagehttps://pypi.org/project/mini-racer/ ↗