Python 3.12.0中ChromaDB已安装仍遇ModuleNotFoundError如何解决？

问题描述 #

我正在开发一个文本文档处理、分块与嵌入的项目，计划将数据存入ChromaDB向量数据库。开发环境为VSCode，使用Python 3.12.0，已安装ChromaDB 0.4.0，但运行代码时出现导入错误。

简化代码 #

from langchain_community.document_loaders import TextLoader, DirectoryLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Chroma

# 加载文档
text_loader_kwargs = {'autodetect_encoding': True}
loader = DirectoryLoader("./new_articles/", glob="./*.txt", loader_cls=TextLoader, loader_kwargs=text_loader_kwargs)
documents = loader.load()

# 创建文本分块
text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
text = text_splitter.split_documents(documents)

# 嵌入并存储到ChromaDB
embeddings = OpenAIEmbeddings()
persist_directory = 'db'
vectordb = Chroma.from_documents(documents=text, embedding=embeddings, persist_directory=persist_directory)

print(vectordb)

错误信息 #

import chromadb.config
ModuleNotFoundError: No module named 'chromadb.config'; 'chromadb' is not a package

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  # 后续堆栈跟踪显示chromadb未找到的ImportError...

已尝试操作 #

• 执行pip install chromadb，包已显示在已安装列表中
• 重新安装ChromaDB
• 检查项目目录是否存在命名冲突（无冲突）

环境详情 #

• Python版本：3.12.0
• ChromaDB版本：0.4.0
• 开发环境：VSCode

解决方案 #

1. 确认Python环境一致性 #

VSCode可能默认使用系统全局Python或其他虚拟环境，需确保当前运行脚本的环境与安装ChromaDB的环境一致：

• 打开VSCode终端，执行which python（Linux/macOS）或where python（Windows），查看当前终端使用的Python路径
• 执行pip --version，确认pip对应的Python版本是否为3.12.0
• 若不一致，点击VSCode状态栏的Python版本，切换到安装了ChromaDB的3.12.0环境

2. 修复版本兼容性问题 #

ChromaDB 0.4.0与Python 3.12存在适配问题，可通过以下方式解决：

• 升级到最新稳定版ChromaDB：

  pip install --upgrade chromadb
  

• 若必须保留0.4.0版本，安装兼容的依赖包：

  pip install pydantic<2.0
  

3. 规范虚拟环境使用 #

• 创建并激活独立虚拟环境后再安装依赖，避免全局环境冲突：

  # 创建虚拟环境
  python -m venv .venv
  # Windows激活
  .venv\Scripts\activate
  # Linux/macOS激活
  source .venv/bin/activate
  # 安装所需包
  pip install chromadb langchain langchain-community langchain-openai
  

4. 验证并修复安装完整性 #

• 在终端执行以下命令验证安装：

  python -c "import chromadb; print(chromadb.__version__)"
  

  若成功输出版本号则安装正常；若仍报错，强制重新安装并清理缓存：

  pip uninstall -y chromadb
  pip install --no-cache-dir chromadb
  

5. 排查目录命名冲突 #

• 确保项目目录下没有名为chromadb.py、chromadb的文件或文件夹，避免覆盖官方包
• 若存在同名内容，重命名后重新运行脚本

内容的提问来源于stack exchange，提问作者Nasim_Reja