BERTopic

BERTopic turns documents, precomputed embeddings, or multimodal inputs into topic models you can fit, inspect, label, visualize, and save.

Install

python -m pip install bertopic

Use only the optional packages that the chosen workflow needs. For example, multimodal image workflows use bertopic[vision], while label and backend workflows may require openai, litellm, langchain, llama-cpp-python, spacy, fastembed, model2vec, gensim, flair, safetensors, or datamapplot.

If you are working from a local checkout to inspect the package, editable install is also fine:

python -m pip install -e .

Quick check

Run the bundled environment check first:

python scripts/check_env.py

Add --smoke for a tiny no-download fit/load-style smoke that uses synthetic documents and precomputed embeddings.

Route map

• sub-skills/topic-modeling/ — build BERTopic models, fit and transform data, run partial_fit, mutate topics, and combine or reduce fitted models.
• sub-skills/embeddings-backends/ — choose embedding backends, build custom embedders, inventory optional backend imports, and handle precomputed or multimodal embeddings.
• sub-skills/vectorizers-ctfidf/ — tune ClassTfidfTransformer, CountVectorizer, and OnlineCountVectorizer for better topic words.
• sub-skills/representations-labeling/ — rerank keywords, generate labels, chain representation models, and manage multi-aspect topic outputs.
• sub-skills/analysis-visualization/ — inspect fitted models with topic tables, hierarchies, distributions, and plots.
• sub-skills/serialization/ — save, reload, and share fitted models locally or through the Hugging Face Hub.

When a task spans more than one route, start with the earliest route in the pipeline and move forward: embeddings → model building → topic-word tuning → labels → analysis → serialization.

Read next

• references/workflows.md for the fastest route through common BERTopic tasks.
• references/troubleshooting.md when imports, optional dependencies, plotting, or save/load fail.
• references/repo-provenance.md before deciding whether this skill matches the current checkout.