Install & Compatibility
Where this runs
tested against v0.1.128 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 47.6s
py 3.11
✕ build_error
✓ 40.1s
py 3.12
✕ build_error
✓ 34s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 53.2s
620MB installed
● package 620MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
App
✓ from embedchain import App
The primary class for creating and interacting with an Embedchain application.
OpenSourceApp
✓ from embedchain import OpenSourceApp
Used to initialize an Embedchain application with open-source LLMs and embedding models (e.g., GPT4All, Sentence Transformers).
This quickstart demonstrates how to create an Embedchain application, add web page data, and query it. By default, Embedchain uses OpenAI's models, requiring the `OPENAI_API_KEY` to be set as an environment variable.
import os
from embedchain import App
# Ensure your OpenAI API key is set as an environment variable
# Or replace os.environ.get with your actual key for testing.
# For production, always use environment variables.
os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "sk-YOUR_OPENAI_KEY")
# Create an Embedchain app instance
app = App()
# Add data sources (e.g., URLs, PDFs, YouTube videos, local files)
app.add("https://en.wikipedia.org/wiki/Elon_Musk")
app.add("https://www.forbes.com/profile/elon-musk")
# Query the app
response = app.query("How many companies does Elon Musk run and name those?")
print(response)
# You can also use the chat interface for conversational queries
# app.chat("Tell me more about Tesla.")
embedchain --version
Debug
Known issues
gotchaChromaDB, the default vector database, can sometimes get corrupted. This often manifests as unexpected errors during operations.fixDelete the `./chroma_db` folder (or your configured ChromaDB path) and re-index your data.
affects: All versions using ChromaDB (default)
gotchaThe first query to an Embedchain application can be significantly slower than subsequent ones. This is due to initial loading of models and data into memory.fixBe aware of this initial delay, especially in user-facing applications. Subsequent queries will be faster.
affects: All versions
gotchaLarge document sets can consume a substantial amount of RAM. For example, processing 4GB of documents might require a minimum of 8GB of RAM.fixMonitor memory usage, especially when dealing with extensive datasets. Consider breaking down extremely large datasets or optimizing your environment.
affects: All versions, scales with data size
gotchaEmbedchain does not provide a straightforward method to update individual documents. If source data changes, the existing indexed document remains.fixThe safest approach to update data is to re-index the entire dataset after making changes, which involves deleting the old index and adding the data again.
affects: All versions
gotchaWhen using OpenAI's API, you might encounter rate limiting issues during intensive embedding or querying operations.fixImplement delays between API calls, switch to a different embedding provider, or explore self-hosted LLM/embedding solutions with `OpenSourceApp`.
affects: All versions using OpenAI API
breakingEmbedchain can introduce unexpected transitive dependencies when integrated into projects already using other GenAI frameworks (e.g., `llama-index`, `crewai`), leading to version conflicts and compatibility issues.fixCarefully manage your project's dependencies. If conflicts arise, try to isolate Embedchain or manually pin conflicting package versions. Regularly check for known incompatibilities.
affects: Potentially any version when combined with other GenAI libraries.
breakingIncorrect configuration of embedding dimensions or incompatible settings between custom embedding models and vector stores (e.g., Qdrant, Ollama) can lead to silent failures or incorrect retrieval, often without clear error messages.fixEnsure that the embedding dimension configured for your embedding model precisely matches the schema or expected dimension of your vector store. Rebuilding indexes after model changes is recommended. Consult the specific vector store and embedding model documentation.
affects: Versions 0.1.125 and higher when using custom configurations.
Errors
Common errors & fixes
TypeError: SegmentAPI.get_or_create_collection() got an unexpected keyword argument 'embedding_function'
This error occurs due to an incompatibility between `embedchain` versions (specifically seen when upgrading from ~0.1.124 to ~0.1.125 or newer) and the underlying ChromaDB, where the collection initialization method changed how it handles the `embedding_function` argument.
fixUpdate ChromaDB to a compatible version (e.g., `pip install chromadb>=0.4.13`) and ensure your `embedchain` configuration explicitly handles collection initialization, for instance, by setting a `collection_name` or providing an `embedder` in the `App` configuration.
embedchain 0.1.128 requires langchain-openai<0.3.0,>=0.2.1, but you have langchain-openai 0.3.14 which is incompatible.
This is a dependency conflict where `embedchain` has a strict requirement for a specific version range of `langchain-openai`, but another installed package (or a manual installation) provides an incompatible version.
fixManually install a compatible version of the conflicting package, e.g., `pip install langchain-openai==0.2.5 --force-reinstall`. It's recommended to use virtual environments to manage project-specific dependencies.
ImportError: Ollama requires extra dependencies. Install with `pip install ollama`
When using `embedchain` with Ollama as an LLM or embedding provider, the specific `ollama` Python client library is a required dependency that needs to be installed separately.
fixInstall the missing Ollama client library using pip: `pip install ollama`.
ModuleNotFoundError: No module named 'embedchain'
This typically happens when `embedchain` is expected by another library (like `crewai-tools`) but is not explicitly installed in the environment or there's a version mismatch in transitive dependencies preventing its proper resolution.
fixEnsure `embedchain` is installed explicitly in your environment: `pip install embedchain`. If using it with other tools, verify that the `embedchain` version is compatible with those tools (e.g., `pip install embedchain==0.1.114` if a specific version is required by `crewai-tools`).
ModuleNotFoundError: No module named 'pandas.core.arrays.arrow.dtype'
This error often arises when running `embedchain` in specific environments (like Docker containers with certain Python versions, e.g., 3.11) and indicates a missing or incompatible sub-dependency related to `pandas` or `pyarrow` that `embedchain` or one of its dependencies relies on.
fixTry upgrading `embedchain` to the latest version (`pip install --upgrade embedchain`), as newer versions often address underlying dependency compatibility issues. If the issue persists, ensure your `pandas` and `pyarrow` installations are compatible with your Python version.
Upgrade
Version history
0.1.128latest on PyPI · released Mar 25, 2025
Audit
Dependencies
openaioptionalUsed for OpenAI's embedding models and ChatGPT API as the Large Language Model (LLM). Requires an `OPENAI_API_KEY` environment variable.
langchainrequiredEmbedchain is built on top of LangChain as an underlying LLM framework for data loading, chunking, and indexing.
chromadbrequiredChromaDB is the default vector database used by Embedchain for storing embeddings.
ollamaoptionalRequired as an extra dependency if using Ollama for LLMs.
sentence-transformersoptionalUsed for open-source embedding models, particularly with `OpenSourceApp`.