tqdm/tqdm · warning · TqdmDeprecationWarning

This function will be removed in tqdm==5.0.0 Please use `tqd

Error message

This function will be removed in tqdm==5.0.0
Please use `tqdm.gui.*` instead of `tqdm._tqdm_gui.*`

What it means

Importing the legacy shim tqdm._tqdm_gui emits a module-level TqdmDeprecationWarning (removal in tqdm 5.0.0); the module merely re-exports tqdm.gui. It signals your code (or a dependency) is using the pre-4.x module path for the matplotlib GUI progress bar.

Source

Thrown at tqdm/_tqdm_gui.py:7

from warnings import warn

from .gui import *  # NOQA
from .gui import __all__  # NOQA
from .std import TqdmDeprecationWarning

warn("This function will be removed in tqdm==5.0.0\n"
     "Please use `tqdm.gui.*` instead of `tqdm._tqdm_gui.*`",
     TqdmDeprecationWarning, stacklevel=2)

View on GitHub (pinned to 96f2e60e45)

Solutions

Replace with from tqdm.gui import tqdm_gui / trange
Locate the stale importer with python -W error to raise on the warning and show the traceback
Upgrade/downgrade the dependency that imports the old path
Suppress if unfixable: filterwarnings('ignore', category=tqdm.std.TqdmDeprecationWarning)

Example fix

# before
from tqdm._tqdm_gui import tqdm_gui

# after
from tqdm.gui import tqdm_gui

Defensive patterns

Strategy: validation

Validate before calling

import warnings
warnings.filterwarnings('error', category=DeprecationWarning)
try:
    import tqdm._tqdm_gui
except DeprecationWarning:
    raise SystemExit('migrate to tqdm.gui')

Prevention

Use tqdm.gui for GUI bars
Search for _tqdm_gui in vendored code and dependencies before tqdm 5.x
Pin tqdm <5 until legacy imports are gone

When it happens

Trigger: `import tqdm._tqdm_gui` or `from tqdm._tqdm_gui import tqdm_gui` at any point in the process.

Common situations: Ancient example code for GUI progress bars, stale dependencies, or copy-pasted snippets predating the tqdm 4.x restructure.

Related errors

AI-assisted analysis of tqdm/tqdm@96f2e60e45 (2026-08-28). Data as JSON: /api/errors/917b35f9d2625094. Report an issue: GitHub.