Install & Compatibility
Where this runs
tested against v3.28.0 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.242s · 85.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.5s · import 1.120s · 35MB
60MB installed
● package 60MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Zep
✓ from zep_cloud.client import Zep
✗ from zep_python.client import ZepClient
zep_cloud and zep_python are different packages with different client classes. Using zep_python client against Zep Cloud endpoints will fail.
ZepClient
✓ from zep.client import ZepClient
✗ from zep_cloud.client import Zep
ZepClient is for self-hosted Community Edition only. Requires a running Zep server on localhost:8000 by default.
Zep Cloud client usage. For Community Edition, use ZepClient from zep-python pointed at your self-hosted server.
from zep_cloud.client import Zep
client = Zep(api_key="your-zep-api-key")
client.memory.add(
"session_abc",
messages=[
{"role_type": "user", "content": "My name is Alice."},
{"role_type": "assistant", "content": "Nice to meet you, Alice."}
]
)
memory = client.memory.get("session_abc")
print(memory.context)
Debug
Known issues
breakingzep-cloud and zep-python are separate packages with incompatible client classes and different APIs. Installing the wrong one silently fails at runtime.fixUse zep-cloud for managed platform. Use zep-python (oss branch build) for self-hosted Community Edition.
affects: all
breakingzep-python v2.x main branch is now the Cloud SDK, not the OSS client. pip install zep-python installs the Cloud-flavoured SDK, breaking self-hosted setups.fixSelf-hosted users should use the oss branch build of zep-python or pin to zep-python < 2.0.0.
affects: zep-python >= 2.0.0
breakingMessage field changed from 'role' to 'role_type' in zep-cloud SDK. Passing 'role' is silently ignored or raises a validation error.fixUse role_type field: {"role_type": "user", "content": "..."} affects: zep-cloud all versions
gotchaSelf-hosted Zep requires a running server process. pip install zep-python alone gives only a client library. All calls raise ConnectionError without the server running.fixRun the Zep server via Docker before making any client calls: docker run -p 8000:8000 ghcr.io/getzep/zep:latest
affects: all
gotchaLangChain integration classes (ZepChatMessageHistory, ZepVectorStore) moved from langchain-community into the zep-cloud package. Importing from langchain_community.memory.zep fails on newer installs.fixImport LangChain integration classes directly from zep_cloud.langchain.
affects: all
Upgrade
Version history
3.28.0latest on PyPI · released Aug 11, 2026
Audit
Dependencies
zep-cloudoptionalManaged platform client. Requires ZEP_API_KEY.
langchain-coreoptionalRequired only if using ZepChatMessageHistory or ZepVectorStore LangChain integration classes.