branca

library0.8.2pypypi✓ verified 24d ago

Branca is a Python library designed to generate complex HTML and JavaScript pages from Python objects. It serves as a low-level base for other visualization libraries, most notably Folium, providing core components like `Figure`, `Element`, and `Colormap`. The current version is 0.8.2, and it maintains an active development cycle with regular patch and minor releases.

web-framework data serialization

pip install branca

github ↗package ↗

INSTALL

IMPORT

SIG · BRANCA

branca

web-frameworkpythonv0.8.2

Install

1.7s avg

Import

378ms

Disk

17MB

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.8.2 · 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.392s · 19.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.364s · 20MB

17MB installed

● package 17MB

Code

Verified usage

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

Figure

✓ from branca.element import Figure

Element

✓ from branca.element import Element

JavascriptLink

✓ from branca.element import JavascriptLink

LinearColormap

✓ from branca.colormap import LinearColormap

StepColormap

✓ from branca.colormap import StepColormap

This quickstart demonstrates how to create a `Figure` object, add external JavaScript links and custom HTML `Element`s to it, and then render the entire structure to an HTML string or save it to a file. It showcases Branca's role as a low-level HTML/JS generation utility.

from branca.element import Figure, Element, JavascriptLink # Create a new Figure object to hold elements f = Figure(width="100%", height="400px") # Add a JavaScript library link (e.g., jQuery) to the figure's head f.add_child(JavascriptLink("https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js")) # Add a simple HTML element to the figure's body f.add_child(Element("<h1>Hello from Branca!</h1><p>This is a basic HTML element generated by Python.</p>")) # Render the figure to an HTML string html_output = f.render() print(html_output[:500]) # Print the first 500 characters of the generated HTML # To save to a file (uncomment to run): # f.save("branca_example.html")

Debug

Known issues

breakingPython 3.7 support was dropped in Branca v0.7.2. Users on Python 3.7 or older must upgrade their Python environment or stick to Branca <0.7.2.

fix

Upgrade your Python interpreter to 3.8 or newer.

affects: >=0.7.2

breakingThe internal `_env` instance attribute was removed from the `Element` class in v0.7.1. Direct access or manipulation of this attribute will cause `AttributeError`.

fix

Avoid direct access to `Element._env`. Use public methods or properties for element manipulation. If highly custom Jinja2 templating is needed, it might require a different approach or contributing to Branca's public API.

affects: >=0.7.1

breakingIn v0.5.0, `Element` changed how it stores HTML content, moving from `data-html` to `srcdoc`. If you have custom parsers or scripts that relied on the `data-html` attribute to extract content, they will break.

fix

Update any custom code that extracts HTML content from Branca elements to look for the `srcdoc` attribute instead of `data-html`.

affects: >=0.5.0

deprecatedThe `split_six` utility function was removed in v0.7.2. While primarily an internal utility, if any custom code used it, it will no longer be available.

fix

Review your codebase for any direct calls to `branca.utilities.split_six` and remove or replace them with equivalent standard Python functionality.

affects: >=0.7.2

gotchaStarting with v0.8.2, `Element` ID generation became customizable. While this offers flexibility, if you relied on the exact default ID generation pattern for JavaScript interactions in previous versions, you might encounter subtle changes or unexpected behavior if IDs change slightly.

fix

If your application relies on predicting element IDs for JavaScript, consider using the new customization options to explicitly define IDs or ensure your JS is resilient to varying ID formats.

affects: >=0.8.2

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'branca'

The 'branca' package is not installed in the Python environment where the code is being executed, or the environment is not correctly configured.

fix

Install the branca package using pip: `pip install branca`

ValueError: The 'branca' package was not installed in a way that PackageLoader understands.

This error often occurs when bundling Python applications with tools like Nuitka or PyInstaller, as `jinja2.PackageLoader` (used by branca) may fail to locate templates within the generated executable.

fix

For PyInstaller, ensure the `branca` package's templates and JSON files are explicitly included in the spec file using `datas`: `datas=[('.\venv\Lib\site-packages\branca\*.json','branca'), ('.\venv\Lib\site-packages\branca\templates','templates')]` (adjust path as needed). Alternatively, some users modify `branca/element.py` to use `jinja2.FileSystemLoader` with a dynamic path.

AttributeError: '_LinearColormaps' object has no attribute 'gnuplot'

This error typically occurs when trying to access a predefined colormap palette by an incorrect attribute name or when using an older, deprecated method for generating colormaps.

fix

Instead of accessing predefined palettes as attributes, import `LinearColormap` or `StepColormap` directly and construct the colormap with a list of colors. For example: `from branca.colormap import LinearColormap; colormap = LinearColormap(colors=['red', 'green', 'blue'], vmin=0, vmax=1)`.

Branca HTML iFrame width in percentage not working

When using `branca.element.IFrame` within visualization libraries like Folium, percentage-based width values might not be correctly interpreted by the rendering environment or browser, leading to incorrect sizing.

fix

Specify the `width` parameter of `branca.element.IFrame` using pixel values (e.g., `width=500`) instead of percentages (e.g., `width='100%'`) to ensure consistent rendering. You may also need to adjust the `height` and `ratio` parameters accordingly.

Issue using branca colormap with folium.raster_layers.ImageOverlay

Older versions of Folium or Branca might have compatibility issues where `folium.raster_layers.ImageOverlay` does not correctly process or display `branca.colormap.LinearColormap` objects.

fix

Upgrade both `folium` and `branca` to their latest versions, as this specific issue has been addressed in newer releases. If the problem persists, ensure the `branca.colormap` is correctly configured with `vmin` and `vmax` that align with your image data.

Upgrade

Version history

0.8.2latest on PyPI · released Oct 6, 2025

Audit

Dependencies

Jinja2requiredUsed for templating HTML and JavaScript content.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/python-visualization/branca ↗

packagehttps://pypi.org/project/branca/ ↗