7.8k stars · MIT · v0.17.4 (2025-12-03) · Track this in Rising ↗
The standard way to turn a long thread into named subtopics with a parent/child hierarchy and a timeline view.
Radar check
What we found when we opened it. Every bar is one fact, with its date.
Last code pushed 24 Oct 2026, 3 days before this check.
Latest release v0.17.4 on 3 Dec 2025.
Public since September 2020, about 6 years.
7,910 stars and 932 forks.
1 commits and 7 new issues in the last 90 days.
97 contributors. 7 pull requests merged in 90 days.
No security policy file says how to report a problem. No published security advisories.
How the bars are scored
- Alive. Days since the last code push: a week or less 100, a month 90, three months 70, six months 50, a year 30, eighteen months 15, older 0.
- Releases. Age of the latest GitHub release, on a similar scale; no bar when the project publishes no releases.
- Maturity. Age of the project: eight years 100, five 90, three 70, two 55, one 40, six months 25, younger 10.
- Adoption. Stars on a log scale: 100,000 stars is 100, 10,000 is 80, 1,000 is 60, 100 is 40.
- Activity. Commits in the last 90 days: 300 or more 100, 100 85, 30 65, 10 45, any 25.
- Community. People who have contributed: 100 or more 100, 30 80, 10 60, 5 40, 2 25, one 10.
- Security. A published security policy 80, none 40; published advisories are listed, not scored.
Checked by Repo Radar on 25 Oct 2026 from the repository on GitHub. Covered in Edition 3.
▶Repo detailsthe review · specs · pros & cons · install
What it does
It runs a pipeline of six steps, which the README names: turning text into numbers, reducing those numbers to fewer dimensions, clustering them, splitting into words, weighting the words, and describing each topic. Every step can be swapped out or removed, which is the project's main design claim. On top of that sit many variations: guided and seed-word modelling where you nudge it toward subjects you care about, supervised and manual assignment, topics over time, a hierarchy of broad and narrow topics, incremental learning through .partial_fit, text and image modelling together, and labels written by a large language model. It ships visualisations for topics, documents, hierarchies, word bars and heat maps, and language="multilingual" covers more than 50 languages. What it does not do is promise a stable answer or state its hardware needs: the README says nothing about memory or scale, warns that its modular design assumes some independence between steps, and that several outputs exist only if particular components are used.
Why it matters
Who it suits. Anyone with thousands of pieces of text and no list of subjects. Support messages, survey answers, reviews, forum threads and long transcripts are the usual cases, and this turns them into a labelled map. The hierarchy and the over-time views are what make it more than a clustering script, because both answer questions people actually ask. Skip it if you have a few hundred documents, because the clustering needs volume to find anything, and skip it if you need the same answer every time, for the reason below.
Verdict. Worth an afternoon, and it is the best-documented library in this corner of the field. Three limits to hold on to. The default settings are memory-hungry, because the dimension-reduction and clustering steps both want the whole set in memory at once, and a small machine will feel it. The clustering is not deterministic, so the same text can produce a slightly different map twice, and anyone looking at a screen will notice. And one group, numbered -1, holds everything the model could not place, which the README says is typically ignored: in its own example on a standard news dataset, that group holds 4,630 documents against 693 in the largest real topic, which tells you how much of the text can end up there. The release is older than the code: version 0.17.4 is from 3 December 2025, but code landed on 22 August 2026, so this is maintained rather than finished. Pair it with a small, fast embedding model and it fits a modest machine.
Summary (Key Points)from the README
Key features
- Topic modeling types: Supports guided, supervised, semi-supervised, manual, multi-topic, hierarchical, class-based, dynamic, online/incremental, multimodal, multi-aspect, text generation/LLM, zero-shot, merge models, and seed words.
- Modular pipeline: Embedding, dimensionality reduction, clustering, tokenization, token weighting, and topic representation can each be swapped out or removed.
- Multiple topic representations: KeyBERTInspired reduces stopwords, and ChatGPT or other OpenAI models can generate labels, summaries, and keywords.
- Multi-aspect representations: Models several topic representations at once instead of running them one by one.
- Multilingual option: `BERTopic(language="multilingual")` selects a model that supports 50+ languages.
- Document-level info: `.get_document_info` returns each document's topic, probability, and whether it is a representative document.
- Visualizations: Offers an LDAvis-style topic view plus charts for hierarchy, similarity, term rank, and topics over time.
- Model persistence: `.save` supports the safetensors format, and `BERTopic.load` restores a saved model.
Ways to install
| Platform or method | What it needs | Effort |
|---|---|---|
| uv | uv installed; installs with sentence-transformers | One command |
| pip | pip installed; installs with sentence-transformers | One command |
Important
- Outlier topic: Topic -1 holds all outlier documents and is typically ignored.
- HDBSCAN dependency: Probabilities and representative documents are only available when HDBSCAN is used.
- Lightweight install: Running without transformers, UMAP, or HDBSCAN (for Model2Vec training or inference) requires a separate tutorial.
- Other embedding models: Using them requires choosing from extra install options that the README lists separately.
- LLM labeling: Generating labels with ChatGPT or other OpenAI models depends on an external model service.
- Subjective evaluation: The README notes that topic model evaluation is subjective, so visual inspection is recommended alongside any metrics.
Written by an AI model from the project’s README; not part of the review, and it can be wrong.
- MIT, mature, and documented far beyond the level usual for a research library.
- Every step of the pipeline can be replaced, so the expensive parts can be swapped for cheap ones.
- Hierarchical and over-time modes map directly onto the two questions people ask of a pile of text.
- The default settings use a lot of memory, and the README publishes no hardware guidance at all.
- Results are not identical between runs, which is confusing when people compare two maps.
- The outlier group can swallow a large share of the text, as its own example shows, and must be handled in anything built on top of it.
python3 -m venv venv source venv/bin/activate pip install bertopic # other ways of turning text into numbers pip install bertopic[flair,gensim,spacy,use] # text and images together pip install bertopic[vision]
