huggingface/transformers · error · ImportError

You need to install rich to use the chat interface. (`pip…

Error message

You need to install rich to use the chat interface. (`pip install rich`)

What it means

The `transformers chat` command renders its interface with the rich library, which is an optional dependency. ChatInterface.__init__ (via its run path) checks is_rich_available() and raises ImportError telling you to `pip install rich` when it is missing. Without rich there is no usable terminal UI, so the command aborts before connecting.

Solutions

pip install rich
Or install the serving extras which include UI deps: pip install "transformers[serving]"
Re-run transformers chat

Example fix

# before
transformers chat  # ImportError: need rich

# after
pip install rich
transformers chat

Defensive patterns

Strategy: validation

Validate before calling

try:
    import rich  # noqa
except ImportError:
    raise SystemExit("pip install rich (or transformers[serving]) before using transformers chat")

Prevention

Install transformers[serving] in environments used for chat/serve
Pin rich in lockfiles for images that run the CLI
Smoke-test `transformers chat --help` in new environments

When it happens

Trigger: Running `transformers chat` in an environment where transformers was installed without optional UI extras and rich is absent; slim Docker images; poetry/uv lock files that dropped rich.

Common situations: Minimal production containers; a fresh venv with only `pip install transformers`; rich removed during dependency pruning or a conflict-resolution downgrade.

Related errors

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/c92111212c830cee. Report an issue: GitHub.

Appendix: source

Thrown at src/transformers/cli/chat.py:379

        config.update(do_sample=True, max_new_tokens=256)  # some default values
        config.update(**parse_generate_flags(generate_flags))
        self.config = config

        self.settings = {"base_url": base_url, "model_id": model_id, "config": self.config.to_dict()}

        # User settings
        self.user = user if user is not None else get_username()

        # Load examples
        if examples_path:
            with open(examples_path) as f:
                self.examples = yaml.safe_load(f)
        else:
            self.examples = DEFAULT_EXAMPLES

        # Check requirements
        if not is_rich_available():
            raise ImportError("You need to install rich to use the chat interface. (`pip install rich`)")

        # Run chat session
        asyncio.run(self._inner_run())

    @staticmethod
    def check_health(url):
        health_url = urljoin(get_service_root_url(url) + "/", "health")
        try:
            output = httpx.get(health_url)
            if output.status_code != 200:
                raise ValueError(
                    f"The server running on {url} returned status code {output.status_code} on health check (/health)."
                )
        except httpx.ConnectError:
            raise ValueError(
                f"No server currently running on {url}. To run a local server, please run `transformers serve` in a"
                f"separate shell. Find more information here: https://huggingface.co/docs/transformers/serving"
            )

View on GitHub (pinned to a597f97485)