py-maidr
Make matplotlib, seaborn, Plotly, and Altair charts accessible — MAIDR (Multimodal Access and Interactive Data Representation) for Python.
Overview
py-maidr makes data visualizations accessible to blind and low-vision readers.
import maidr and your existing plotting code renders an interactive figure that
can be navigated by keyboard, heard as sonification, read on a braille
display, and described as text — the same chart in four modalities instead
of one.
Nothing about how you plot changes. py-maidr patches matplotlib and seaborn at
import time, so plt.show() produces accessible HTML instead of a static image;
Plotly and Altair figures go through the same maidr.show() entry point. It
works in a plain script, a Jupyter notebook, Quarto, Shiny, and Streamlit.
Quickstart
import matplotlib.pyplot as plt
import seaborn as sns
import maidr # the whole integration
penguins = sns.load_dataset("penguins")
fig, ax = plt.subplots()
sns.barplot(x="species", y="body_mass_g", data=penguins, ax=ax)
maidr.show(fig)
maidr.save_html(fig, "penguins.html") writes the same plot to a standalone HTML
file instead of displaying it. Because importing maidr also activates its
matplotlib backend, a plain plt.show() renders accessible output too.
What is supported
| Plotting libraries | matplotlib, seaborn (including seaborn.objects), Plotly, Altair — plus mplfinance for financial charts (candlestick, volume, moving averages) |
| Environments | Python scripts, Jupyter, Quarto, Shiny for Python, Streamlit |
| Plot types | 38 — see Plot Type Stability for which fifteen are settled and which twenty-three are experimental |
Plot types not yet supported fall back to a static image with a warning, so a plot is never lost.
Keyboard shortcuts
Press Tab (or click) to focus a rendered plot, move between data points with the arrow keys, and toggle B braille, T text, S sonification, and R review mode. Four global shortcuts open maidr's own interfaces:
| Action | Windows / Linux | macOS |
|---|---|---|
| Show or hide the keyboard shortcut help | Ctrl + / | Command + / |
| Open the command palette listing every available command | Ctrl + Shift + P | Command + Shift + P |
| Open the AI chat (requires your own API key, entered in Settings, or a local Ollama server) | Shift + / (that is, ?) | Shift + / (?) |
| Open Settings | Ctrl + , | Command + , |
The full list, including autoplay, label announcements, and layer switching, is in the maidr controls documentation.
Install and Upgrade
# install the latest release from PyPI
pip install -U maidr
# or install the development version from GitHub
pip install -U git+https://github.com/xability/py-maidr.git
User Guide
Please visit the user guide page.
Offline and Restricted-Network Use
py-maidr loads its JavaScript from a CDN by default, and resolves the current published version so browsers cannot serve a stale cached copy. That costs one bounded outbound request, the first time a plot is rendered. import maidr itself makes no request.
If you work air-gapped, behind a proxy, or in CI:
export MAIDR_CDN_VERSION=bundled # serve the version in this wheel, no lookup
export MAIDR_USE_CDN=false # or skip the CDN entirely
bundled is usually the best choice for restricted networks: it emits an immutable
CDN URL — so browser caching still works correctly — without contacting anything.
It is also the only one of the two that covers Altair charts: the Altair adapter
has no offline path and always references the CDN, so MAIDR_USE_CDN=false does not
apply to it, while MAIDR_CDN_VERSION=bundled still removes the lookup.
A DotPad tactile display needs the
vendor's SDK, which maidr.js fetches from jsDelivr the first time a device is
connected rather than bundling its 14 MB braille engine. To take that offline too,
download the pinned copy once and every use_cdn=False document carries it in
its lib/ folder:
maidr.download_dotpad_sdk() # once; ~14 MB into a per-user cache
maidr.save_html(fig, "chart.html", use_cdn=False)
See Offline Use and the JavaScript Bundle for the full set of options.
Example Code
We provide some example code for using py-maidr with matplotlib, seaborn, Jupyter Notebook, Quarto, Shiny, and Streamlit.
Shiny support requires the optional extra pip install "maidr[shiny]", which
provides output_maidr() and @render_maidr in maidr.widget.shiny.
Streamlit support requires pip install "maidr[streamlit]", which provides
render_maidr() and maidr_html() in maidr.widget.streamlit.
Using with AI coding agents
If an AI coding agent (Claude Code, Codex, Cursor, GitHub Copilot, and others) writes your plotting code, install the
maidr skill with npx skills add xability/maidr-skill. The agent then
routes every matplotlib, seaborn, Plotly, or Altair chart through py-maidr, verifies the output, and hands back an
accessible HTML file or chat artifact instead of a static image.
Contributing
Bug reports, plot types and documentation fixes are all welcome — see CONTRIBUTING.md for how to set up a development environment and shape a change, and CONDUCT.md for our code of conduct.
License
GPL-3.0-or-later. See LICENSE.
2 maintainers
Metadata
2 maintainers
Release files for maidr 1.24.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| maidr-1.24.0.tar.gz | 1.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| maidr-1.24.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.9 MB
Release files / maidr-1.24.0.tar.gz
| Download URL | maidr-1.24.0.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
adcd6f443f391f1c7f0bd8b24eb328761aa5fa801b80d33471edd82887c2eca5
|
|
BLAKE2b-256 checksum How to use checksums |
7f40bb4ed8fb5255518b912b884aa166bfd76d7a903c02f0a2f26e0d3128441b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / maidr-1.24.0-py3-none-any.whl
| Download URL | maidr-1.24.0-py3-none-any.whl |
|---|---|
| Size | 1.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f07b4996cc25443882bdc0636d5a793129e966f9cce0f2c4f47633f0386aed3c
|
|
BLAKE2b-256 checksum How to use checksums |
2141cec2ebf0e45007f8e69aad6b21d22454407188b696fac09535649602b9a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
