{"record":{"id":"a77ef5e19561c924","repo":"chroma-core/chroma","slug":"91myour-system-has-an-unsupported-version-of-sql","errorCode":null,"errorMessage":"\u001b[91mYour system has an unsupported version of sqlite3. Chroma requires sqlite3 >= 3.35.0.\u001b[0m\n\u001b[94mPlease visit https://docs.trychroma.com/troubleshooting#sqlite to learn how to upgrade.\u001b[0m","messagePattern":"\u001b\\[91mYour system has an unsupported version of sqlite3\\. Chroma requires sqlite3 >= 3\\.35\\.0\\.\u001b\\[0m\n\u001b\\[94mPlease visit https://docs\\.trychroma\\.com/troubleshooting#sqlite to learn how to upgrade\\.\u001b\\[0m","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"chromadb/__init__.py","lineNumber":153,"sourceCode":"except ImportError:\n    is_client = False\n\nif not is_client:\n    import sqlite3\n\n    if sqlite3.sqlite_version_info < (3, 35, 0):\n        if IN_COLAB:\n            # In Colab, hotswap to pysqlite-binary if it's too old\n            import subprocess\n            import sys\n\n            subprocess.check_call(\n                [sys.executable, \"-m\", \"pip\", \"install\", \"pysqlite3-binary\"]\n            )\n            __import__(\"pysqlite3\")\n            sys.modules[\"sqlite3\"] = sys.modules.pop(\"pysqlite3\")\n        else:\n            raise RuntimeError(\n                \"\\033[91mYour system has an unsupported version of sqlite3. Chroma \\\n                    requires sqlite3 >= 3.35.0.\\033[0m\\n\"\n                \"\\033[94mPlease visit \\\n                    https://docs.trychroma.com/troubleshooting#sqlite to learn how \\\n                    to upgrade.\\033[0m\"\n            )\n\n\ndef configure(**kwargs) -> None:  # type: ignore\n    \"\"\"Override Chroma's default settings, environment variables or .env files\"\"\"\n    global __settings\n    __settings = chromadb.config.Settings(**kwargs)\n\n\ndef get_settings() -> Settings:\n    return __settings\n\n","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/__init__.py#L135-L171","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)\""],"exampleFix":"# before\nimport chromadb  # RuntimeError: unsupported version of sqlite3\n\n# after\nimport sys\nimport pysqlite3  # pip install pysqlite3-binary\nsys.modules['sqlite3'] = sys.modules.pop('pysqlite3')\nimport chromadb","handlingStrategy":"validation","validationCode":"import sqlite3\n\nMIN_SQLITE = (3, 35, 0)\nif sqlite3.sqlite_version_info < MIN_SQLITE:\n    try:\n        import pysqlite3  # pip install pysqlite3-binary\n        import sys\n        sys.modules['sqlite3'] = sys.modules.pop('pysqlite3')\n    except ImportError:\n        raise RuntimeError(\n            f'sqlite3 {sqlite3.sqlite_version} < 3.35.0; '\n            'install pysqlite3-binary or use a chroma server + HttpClient'\n        )\n\nimport chromadb  # safe now","typeGuard":null,"tryCatchPattern":"try:\n    import chromadb\nexcept RuntimeError as e:\n    if 'sqlite3' in str(e):\n        # apply the pysqlite3 swap (see validationCode) and retry the import,\n        # or switch to chromadb.HttpClient against a server\n        raise\n    raise","preventionTips":["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"],"tags":["python","sqlite","environment","import-error","version-check"],"backgroundTag":"sqlite-version-unsupported","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}