Environment:Explodinggradients Ragas Python Runtime Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, NLP, LLM_Evaluation |
| Last Updated | 2026-02-10 12:00 GMT |
Overview
Python 3.9+ environment with core dependencies for the Ragas LLM evaluation framework, including OpenAI, LangChain, Pydantic, and numpy.
Description
This environment defines the base runtime required for all Ragas operations. It is a pure CPU-based Python environment with no GPU requirements. The core dependency stack includes the OpenAI Python client, the LangChain ecosystem (langchain, langchain-core, langchain-community, langchain_openai), Pydantic for data validation, numpy for numerical operations, and the instructor library for structured LLM output. The build system uses setuptools with setuptools_scm for version management.
Usage
This environment is the mandatory prerequisite for every Ragas operation. All evaluation workflows, test data generation, metric computation, and experiment orchestration depend on this base environment. No Ragas code can run without these dependencies installed.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Any (Linux, macOS, Windows) | Pyright platform is set to "All" |
| Python | >= 3.9 | Configured in `pyproject.toml` line 4; Ruff targets `py39` |
| Disk | ~500MB | For core dependencies and cache directory at `~/.cache/ragas` |
Dependencies
System Packages
No system-level packages are required beyond a Python 3.9+ interpreter.
Python Packages (Core / Mandatory)
- `numpy` >= 1.21.0, < 3.0.0
- `datasets` >= 4.0.0
- `tiktoken` (unconstrained)
- `pydantic` >= 2.0.0
- `nest-asyncio` (unconstrained)
- `appdirs` (unconstrained)
- `diskcache` >= 5.6.3
- `typer` (unconstrained)
- `rich` (unconstrained)
- `openai` >= 1.0.0
- `tqdm` (unconstrained)
- `instructor` (unconstrained)
- `pillow` >= 10.4.0
- `networkx` (unconstrained)
- `scikit-network` (unconstrained)
- `langchain` (unconstrained)
- `langchain-core` (unconstrained)
- `langchain-community` (unconstrained)
- `langchain_openai` (unconstrained)
Python Packages (Implicit / Transitive)
- `requests` -- used directly by analytics module
- `tenacity` -- used directly by retry/backoff logic
Build System
- `setuptools` >= 64
- `setuptools_scm` >= 8
Credentials
The following environment variables may be set:
- `RAGAS_DO_NOT_TRACK`: Set to `"true"` to disable anonymous usage analytics. Default: tracking enabled.
- `RAGAS_DEBUG`: Set to `"true"` to enable verbose debug logging and stack traces.
- `RAGAS_CACHE_HOME`: Override the default cache directory location (default: `~/.cache/ragas`).
- `XDG_CACHE_HOME`: Standard XDG cache base directory; used if `RAGAS_CACHE_HOME` is not set.
Quick Install
# Minimal install (core only)
pip install ragas
# Full install with all optional features
pip install "ragas[all]"
# Development install (minimal)
pip install -e ".[dev-minimal]"
# Development install (full)
uv sync --group dev
Code Evidence
Python version constraint from `pyproject.toml:4`:
requires-python = ">=3.9"
Core dependencies from `pyproject.toml:6-29`:
dependencies = [
"numpy>=1.21.0,<3.0.0",
"datasets>=4.0.0",
"tiktoken",
"pydantic>=2.0.0",
"nest-asyncio",
"appdirs",
"diskcache>=5.6.3",
"typer",
"rich",
"openai>=1.0.0",
"tqdm",
"instructor",
"pillow>=10.4.0",
"networkx",
"scikit-network",
"langchain",
"langchain-core",
"langchain-community",
"langchain_openai",
]
Cache directory resolution from `src/ragas/utils.py:30-35`:
@lru_cache(maxsize=1)
def get_cache_dir() -> str:
DEFAULT_XDG_CACHE_HOME = "~/.cache"
xdg_cache = os.getenv("XDG_CACHE_HOME", DEFAULT_XDG_CACHE_HOME)
default_ragas_cache = os.path.join(xdg_cache, "ragas")
return os.path.expanduser(os.getenv("RAGAS_CACHE_HOME", default_ragas_cache))
Analytics opt-out from `src/ragas/_analytics.py:41-49`:
RAGAS_DO_NOT_TRACK = "RAGAS_DO_NOT_TRACK"
@lru_cache(maxsize=1)
def do_not_track() -> bool:
return os.environ.get(RAGAS_DO_NOT_TRACK, str(False)).lower() == "true"
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `ImportError: nest_asyncio` | Running in Jupyter without nest_asyncio | `pip install nest_asyncio` |
| `RuntimeError: Cannot execute nested async code with uvloop` | Using uvloop (common in FastAPI) with sync API | Use `aevaluate()` or `@experiment` in async context |
| `ModuleNotFoundError: ragas._version` | Package not installed in editable mode | Run `pip install -e .` or `uv sync` |
Compatibility Notes
- Jupyter Notebooks: Requires `nest_asyncio` for sync API calls. Ragas auto-detects notebook environments and patches the event loop.
- uvloop: Incompatible with `nest_asyncio`. Applications using uvloop (FastAPI, Starlette) must use async APIs (`aevaluate()`, `@experiment` decorator).
- Python 3.10+: Required only for `mkdocs-llmstxt` (documentation build). Runtime works on 3.9+.