Install & Compatibility
Where this runs
tested against v4.0.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.615s · 446.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 16.6s · import 0.862s · 415MB
434MB installed
● package 434MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
annotated_text
✓ from annotated_text import annotated_text
✗ from st_annotated_text import annotated_text
The top-level package for import is `annotated_text`, not `st_annotated_text`.
This example demonstrates basic usage, including simple annotations, custom background colors, and nested list structures for more complex text segments.
import streamlit as st
from annotated_text import annotated_text
st.set_page_config(layout='centered', page_title='Annotated Text Demo')
st.title("My Annotated Text App")
annotated_text(
"This ",
("is", "Verb"),
" some ",
("annotated", "Adj"),
("text", "Noun"),
" for those of ",
("you", "Pronoun"),
" who ",
("like", "Verb"),
" this sort of ",
("thing", "Noun"),
"."
)
st.subheader("Custom Colors and No Label")
annotated_text(
"And here's a ",
("word", "", "#faf"),
" with a fancy background but no label."
)
st.subheader("Nested Lists for Complex Structures")
my_complex_list = [
"Hello ",
["my ", ("dear", "Adj"), " "],
("world", "Noun"),
"."
]
annotated_text(my_complex_list)
Debug
Known issues
gotchaThe correct import path for the `annotated_text` function is `from annotated_text import annotated_text`. Attempting to import from `st_annotated_text` (e.g., `from st_annotated_text import annotated_text`) will result in a `ModuleNotFoundError`.fixAlways use `from annotated_text import annotated_text`.
affects: <1.1.0 and common user typos
gotchaFor very long strings or complex annotations, the displayed text may be truncated within the Streamlit app. This is often due to the underlying `iframe` component not having enough height. You can often mitigate this by passing a `height` keyword argument to `annotated_text()`.fixPass `height=N` (e.g., `height=200`) to the `annotated_text()` function to allocate more vertical space.
affects: All versions
breakingVersion 4.0.2 introduced 'Compatibility with both older and current htbuilder versions.' This suggests that prior 4.x.x versions might have had specific `htbuilder` version requirements, potentially leading to runtime errors if `htbuilder` was not correctly aligned. Ensure `htbuilder` is up-to-date or compatible with your `st-annotated-text` version.fixUpgrade `st-annotated-text` to 4.0.2 or later, and ensure `htbuilder` is also updated (`pip install --upgrade htbuilder`).
affects: Potentially 4.0.0, 4.0.1
gotchaWhen trying to combine `annotated_text` output (or `annotation` from `htbuilder`) directly within `st.markdown(..., unsafe_allow_html=True)`, it can lead to parsing issues or incorrect rendering. Streamlit's HTML sanitizer might struggle with fragmented HTML.fixWrap the entire HTML output in a single parent HTML element (e.g., `h3` from `htbuilder`) before passing it to `st.markdown` to ensure proper parsing.
affects: All versions
gotchaGlobal customization of annotation styles (e.g., `SHOW_LABEL_SEPARATOR`, `BORDER_RADIUS`, `PADDING`) is done by importing and modifying variables in the `annotated_text.parameters` module. This is less explicit than passing arguments directly to the main function.fixImport `parameters` from `annotated_text` and modify its attributes (e.g., `from annotated_text import parameters; parameters.SHOW_LABEL_SEPARATOR = False`) before calling `annotated_text`.
affects: All versions
Upgrade
Version history
4.0.2latest on PyPI · released Jan 23, 2025
Audit
Dependencies
streamlitrequiredRequired to run the Streamlit custom component.
htbuilderrequiredUsed for building HTML elements; recent versions include compatibility fixes.