Sphinx Contrib JSMath

1.0.1 verified Tue May 12 auth: no python install: verified

Sphinxcontrib-jsmath is a Sphinx extension that enables rendering of display math in HTML output via JavaScript, utilizing the older jsMath library. It is often chosen for its smaller JavaScript package size compared to newer alternatives like MathJax. The current version is 1.0.1, last released in January 2019, but it continues to receive compatibility updates for newer Sphinx versions through various distribution packages.

pip install sphinxcontrib-jsmath

Warnings

gotcha The underlying jsMath library, on which this Sphinx extension relies, is no longer actively developed. This means new math rendering features or bug fixes specific to the JavaScript rendering engine are unlikely to be implemented. ↓

fix Be aware of the limitations of an older rendering engine. For more actively maintained math rendering, consider `sphinx.ext.mathjax`.

breaking The import path for this extension changed. For Sphinx versions 4.0 and newer, `sphinx.ext.jsmath` is no longer a valid entry for `extensions` in `conf.py`. ↓

fix Always use `'sphinxcontrib.jsmath'` in your `extensions` list in `conf.py`. This change was introduced in Sphinx 2.0, with the alias for the old path removed in 4.0.

gotcha The `jsmath_path` configuration variable has no default value. You must explicitly set this path in your `conf.py` to the location of the `jsMath/easy/load.js` file. Failure to do so will result in math not being rendered in your HTML output. ↓

fix Ensure `jsmath_path` is correctly configured in `conf.py` to point to the `jsMath/easy/load.js` file, typically within your `_static` directory or an external URL.

gotcha Due to the `jsMath` library's age, it may have known bugs or suboptimal rendering with very old or specific browser versions (e.g., Opera 9.5, MSIE). While these browsers are largely obsolete, it highlights the legacy nature of the underlying technology. ↓

fix Modern browsers should render correctly, but be aware of potential issues with extremely old or niche browser environments.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.00s 17.8M

3.10 alpine (musl) - - 0.00s 17.8M

3.10 slim (glibc) wheel 1.4s 0.00s 18M

3.10 slim (glibc) - - 0.00s 18M

3.11 alpine (musl) wheel - 0.00s 19.6M

3.11 alpine (musl) - - 0.00s 19.6M

3.11 slim (glibc) wheel 1.6s 0.00s 20M

3.11 slim (glibc) - - 0.00s 20M

3.12 alpine (musl) wheel - 0.00s 11.5M

3.12 alpine (musl) - - 0.00s 11.5M

3.12 slim (glibc) wheel 1.5s 0.00s 12M

3.12 slim (glibc) - - 0.00s 12M

3.13 alpine (musl) wheel - 0.00s 11.3M

3.13 alpine (musl) - - 0.00s 11.1M

3.13 slim (glibc) wheel 1.4s 0.00s 12M

3.13 slim (glibc) - - 0.00s 12M

3.9 alpine (musl) wheel - 0.00s 17.3M

3.9 alpine (musl) - - 0.00s 17.3M

3.9 slim (glibc) wheel 1.7s 0.00s 18M

3.9 slim (glibc) - - 0.00s 18M

Imports

Extension Configuration
wrong
```
extensions = ['sphinx.ext.jsmath']
```
correct
```
extensions = ['sphinxcontrib.jsmath']
```
The old 'sphinx.ext.jsmath' path was moved to 'sphinxcontrib.jsmath' in Sphinx 2.0 and the alias removed in Sphinx 4.0. Always use 'sphinxcontrib.jsmath' for modern Sphinx versions.

Quickstart last tested: 2026-04-24

To enable sphinxcontrib-jsmath, add 'sphinxcontrib.jsmath' to the `extensions` list in your Sphinx project's `conf.py` file. Additionally, you must configure `jsmath_path` to point to the `jsMath/easy/load.js` file, which typically resides in your Sphinx project's `_static` directory after you've manually downloaded the jsMath library.

# conf.py

# Add 'sphinxcontrib.jsmath' to the list of extensions
extensions = [
    'sphinxcontrib.jsmath',
    # ... other extensions
]

# Set the path to the jsMath library.
# This example assumes jsMath is placed in your Sphinx project's _static directory,
# e.g., <your_project_root>/_static/jsMath/easy/load.js
# You need to download the jsMath library separately and place it there.
# If jsMath is hosted externally, provide the full URL.
jsmath_path = 'jsMath/easy/load.js'