chroma-core/chroma · critical · RuntimeError

[91mYour system has an unsupported version of sqlite3. Chro

Error message

[91mYour system has an unsupported version of sqlite3. Chroma requires sqlite3 >= 3.35.0.[0m
[94mPlease visit https://docs.trychroma.com/troubleshooting#sqlite to learn how to upgrade.[0m

What it means

On import, chromadb checks the interpreter's sqlite3 library version because its SQLite persistence layer requires >= 3.35.0 (chromadb/__init__.py:149-158). On Google Colab it hot-swaps in pysqlite3-binary; everywhere else `import chromadb` raises this RuntimeError with ANSI-colored text linking to the troubleshooting page. The failure happens at import time, before any client can be created.

Source

Thrown at chromadb/__init__.py:153

except ImportError:
    is_client = False

if not is_client:
    import sqlite3

    if sqlite3.sqlite_version_info < (3, 35, 0):
        if IN_COLAB:
            # In Colab, hotswap to pysqlite-binary if it's too old
            import subprocess
            import sys

            subprocess.check_call(
                [sys.executable, "-m", "pip", "install", "pysqlite3-binary"]
            )
            __import__("pysqlite3")
            sys.modules["sqlite3"] = sys.modules.pop("pysqlite3")
        else:
            raise RuntimeError(
                "\033[91mYour system has an unsupported version of sqlite3. Chroma \
                    requires sqlite3 >= 3.35.0.\033[0m\n"
                "\033[94mPlease visit \
                    https://docs.trychroma.com/troubleshooting#sqlite to learn how \
                    to upgrade.\033[0m"
            )


def configure(**kwargs) -> None:  # type: ignore
    """Override Chroma's default settings, environment variables or .env files"""
    global __settings
    __settings = chromadb.config.Settings(**kwargs)


def get_settings() -> Settings:
    return __settings

View on GitHub (pinned to aecdd12c8a)

Solutions

Apply the documented pysqlite3 swap (what the Colab branch does): pip install pysqlite3-binary, then sys.modules['sqlite3'] = sys.modules.pop('pysqlite3') before importing chromadb
Upgrade the runtime: newer OS/Python build, or conda/pip install a sqlite >= 3.35
Avoid local sqlite entirely: run a Chroma server (chroma run or the chromadb/chroma Docker image) and use HttpClient
Verify first: python -c "import sqlite3; print(sqlite3.sqlite_version)"

Example fix

# before
import chromadb  # RuntimeError: unsupported version of sqlite3

# after
import sys
import pysqlite3  # pip install pysqlite3-binary
sys.modules['sqlite3'] = sys.modules.pop('pysqlite3')
import chromadb

Defensive patterns

Strategy: validation

Validate before calling

import sqlite3

MIN_SQLITE = (3, 35, 0)
if sqlite3.sqlite_version_info < MIN_SQLITE:
    try:
        import pysqlite3  # pip install pysqlite3-binary
        import sys
        sys.modules['sqlite3'] = sys.modules.pop('pysqlite3')
    except ImportError:
        raise RuntimeError(
            f'sqlite3 {sqlite3.sqlite_version} < 3.35.0; '
            'install pysqlite3-binary or use a chroma server + HttpClient'
        )

import chromadb  # safe now

Try / catch

try:
    import chromadb
except RuntimeError as e:
    if 'sqlite3' in str(e):
        # apply the pysqlite3 swap (see validationCode) and retry the import,
        # or switch to chromadb.HttpClient against a server
        raise
    raise

Prevention

Run a preflight check (sqlite3.sqlite_version_info) in Dockerfiles/CI before installing chromadb
Pin base images that ship sqlite >= 3.35 (Debian bookworm, Ubuntu 22.04+)
Prefer HttpClient against a Chroma server on locked-down or legacy hosts

When it happens

Trigger: import chromadb on a Python interpreter linked against sqlite older than 3.35 — CentOS/RHEL 7 (sqlite 3.7.17), older Debian/Ubuntu images, some bundled macOS/Windows Python builds, older AWS Lambda runtimes.

Common situations: Docker base images pinned to old distros; a system upgrade swapping libsqlite3 under an existing Python; CI runners differing from developer machines; the raw ANSI escape codes showing up in logs when stderr is not a TTY.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/a77ef5e19561c924. Report an issue: GitHub.

[91mYour system has an unsupported version of sqlite3. Chro