Minimal, modern embedded V8 for Python.

pip install py_mini_racer==0.1.15


Python Mini Racer

Minimal, modern embedded V8 for Python.

  • Free software: ISC license



  • Unicode support
  • Thread safe
  • Re-usable contexts
  • Binary object is Python agnostic

MiniRacer can be easily used by Django or Flask projects to minify assets, run babel or compile CoffeeScript.


py_mini_racer is straightforward to use:

>>> from py_mini_racer import py_mini_racer
>>> ctx = py_mini_racer.MiniRacer()
>>> ctx.eval('1+1')
>>> ctx.eval("var x = {company: 'Sqreen'};")
>>> print ctx.eval(u"'\N{HEAVY BLACK HEART}'")
>>> ctx.eval("var fun = () => ({ foo: 1 });")
{u'foo': 1}

Variables are kept inside of a context:

>>> ctx.eval("")

You can give directly a custom JSON encoder when sending non-JSON encodable parameters:

import json

from datetime import datetime

class CustomEncoder(json.JSONEncoder):

        def default(self, obj):
            if isinstance(obj, datetime):
                return obj.isoformat()

            return json.JSONEncoder.default(self, obj)
>>> ctx.eval("var f = function(args) { return args; }")
>>>"f",, encoder=CustomEncoder)

PyMiniRacer is ES6 capable:

>>> ctx.eval("[1,2,3].includes(5)")

V8 heap information can be retrieved:

>>> ctx.heap_stats()
{u'total_physical_size': 1613896,
 u'used_heap_size': 1512520,
 u'total_heap_size': 3997696,
 u'total_heap_size_executable': 3145728,
 u'heap_size_limit': 1501560832}


PyMiniRacer is compatible with Python 2 and Python 3. Wheels are generated for python 2.7 and python 3.4 to python 3.6.

Binary builds availability

The PyMiniRacer binary builds have been tested on x86_64 with:

  • OSX 10.10
  • Ubuntu >= 12.04
  • Debian >= 7
  • CentOS >= 6

You need pip >= 8.1 to install the wheels - you can check and upgrade yours in this way:

$ pip --version
$ pip install --upgrade pip

It should work on any Linux with a libc >= 2.12 and a wheel compatible pip (>= 8.1).

If you have a up-to-date pip and it doesn't use a wheel, you might have an environment for which no wheel is built. Please open an issue.


We built Python wheels (prebuilt binaries) for OSX 64 bits and Linux 64 bits - most recent distributions. You need pip >= 1.4 and setuptools >= 0.8.

$ pip install py-mini-racer


You can build v8 with the command:

$ python build_v8

You can also build the ctype extension:

$ python build_ext

Which automatically builds v8.

You can generate a wheel with the command:

$ python bdist_wheel

which builds v8, the extension, and generates a wheel.

Notes for building on macOS

The legacy Python binary builds (OSX 10.6) need to be downloaded from:

They will allow to build a wheel compatible with former OSX versions.

If you're having build issues, you may either have to run the build a second time (which will be much faster than the first run) or run the following command before running the first build:

export LDSHARED="clang++ -bundle -undefined dynamic_lookup -arch i386 -arch x86_64"

Notes for building on Travis

The V8 build is cached in order to make the Travis builds faster.

Whenever V8 is updated, the caches need to be flushed on Travis here.


If you want to run the tests, you need to build V8 first, then launch:

$ python test --addopts tests


Built with love by Sqreen.

PyMiniRacer launch was described in this blog post.

PyMiniRacer is inspired by mini_racer, built for the Ruby world by Sam Saffron.

Tools used in rendering this package:


Export V8 version. Fix circular structures export.