Introduction

This error is usually a dependency compatibility problem, not a Top2Vec modeling problem. The keyword cachedir comes from older library APIs, while newer versions of some dependencies expect a different parameter name such as location. When Top2Vec or one of its transitive dependencies uses the older call pattern in an environment with newer packages, the import can fail before you even create a model.

What the Error Usually Means

The message:

__init__() got an unexpected keyword argument 'cachedir'

typically points to an older call site using:

Memory(cachedir=...)

against a newer version of the library where that constructor signature changed.

In Python ML stacks, this kind of problem often comes from version skew between:

• Top2Vec
• joblib
• umap-learn
• hdbscan
• scikit-learn

The exact failing package can vary, but the pattern is the same: one dependency expects an older API and another dependency no longer provides it.

Inspect the Installed Versions First

Before changing anything, inspect the environment:

1python -m pip show top2vec
2python -m pip show joblib
3python -m pip show umap-learn
4python -m pip show hdbscan
5python -m pip show scikit-learn

If the environment has been upgraded piecemeal over time, mismatched versions are the most likely explanation.

Upgrade the Stack Together or Pin Compatible Versions

The cleanest fix is usually to install Top2Vec and its key dependencies in a fresh environment rather than patching one package at a time in place.

Example:

1python -m venv .venv
2source .venv/bin/activate
3python -m pip install --upgrade pip
4python -m pip install top2vec

If you need a reproducible project environment, pin the versions that work together in your lock file or requirements file after verifying the import succeeds.

Why Downgrading One Package Sometimes Works

If the break is specifically caused by an older caller passing cachedir into a newer package, downgrading that dependency to a compatible release can work. But treat that as an environment compatibility fix, not as a general Top2Vec rule.

The important engineering point is this:

• do not guess blindly
• identify which package raises the error
• then either upgrade the whole compatible stack or pin the specific compatible versions

Piecemeal downgrades can easily trade one import error for another.

Reproduce the Import in Isolation

Use a minimal test instead of debugging through a larger notebook or app:

from top2vec import Top2Vec

print("import ok")

If that fails, the problem is in the environment. If it succeeds, then any later failure likely comes from how the broader project is configured.

Avoid Mixing Old Project Environments

Many of these failures happen in notebooks or long-lived environments where packages from unrelated experiments coexist. NLP and topic-modeling stacks are especially sensitive because Top2Vec pulls in several heavy dependencies.

A clean environment per project is usually the safest approach:

• one environment for the Top2Vec project
• pinned requirements
• no opportunistic upgrades in the middle of active work

That discipline prevents subtle import breakage later.

When Local Code Is the Problem

If your own code is passing cachedir somewhere, remove it or update the call to match the current library API. The import error message can make it look like Top2Vec itself is broken when the real issue is an application wrapper or helper module using stale arguments.

Search the project for the old parameter:

rg "cachedir"

If you find explicit usage in your own code, update that first before blaming the dependency stack.

Common Pitfalls

The biggest mistake is trying random upgrades and downgrades without checking which package actually raises the error. Another is debugging inside a polluted environment where unrelated package changes have accumulated over months. Developers also assume the problem is inside Top2Vec itself when the issue may be a transitive dependency or even their own helper code. A clean environment and a minimal import test usually reveal the problem faster than trial-and-error package churn.

Summary

• The cachedir error usually indicates a dependency API mismatch, not a modeling bug.
• Check the installed versions of Top2Vec and related dependencies first.
• Prefer a clean environment with compatible package versions over ad hoc patching.
• Use a minimal from top2vec import Top2Vec test to isolate the problem.
• Search your own codebase for cachedir in case stale local code is involved.
• Pin working versions once the environment is stable.