# What Are the Dependencies for Onyx? Core Libraries and Optional Groups Explained

> Discover Onyx dependencies in pyproject.toml. Understand core libraries and optional groups like backend, model_server, dev, and ee to optimize your installation.

- Repository: [Onyx/onyx](https://github.com/onyx-dot-app/onyx)
- Tags: deep-dive
- Published: 2026-03-28

---

**Onyx declares all runtime requirements in the top-level [`pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/pyproject.toml) file, splitting them into five logical groups—core, backend, model_server, dev, and ee—so you install only what your deployment requires.**

Onyx is an open-source Gen-AI and Enterprise Search platform maintained at `onyx-dot-app/onyx`. Understanding the **dependencies for Onyx** is essential before deploying the multi-component architecture, as the project uses optional extras to separate lightweight API requirements from heavy ML stacks and development tooling.

## How Onyx Structures Its Dependencies

According to the `onyx-dot-app/onyx` source code, the project organizes requirements into logical extras inside the root [`pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/pyproject.toml). This design lets operators install minimal libraries for a specific service or pull everything needed for full-stack development.

The five dependency groups declared in [`pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/pyproject.toml) are:

- **Core** – Lines 11-30: Shared libraries used by the backend, model-server, and CLI
- **Backend** – Lines 33-134: Full service stack including Celery, databases, and connector SDKs  
- **Model Server** – Lines 84-91: Heavy-weight ML libraries for embedding and inference
- **Dev** – Lines 136-175: Linting, testing, and debugging tools
- **EE** – Lines 78-80: Enterprise Edition analytics features

## Core Dependencies (Always Installed)

The **core** group contains universal requirements that ship with every installation. These libraries support the HTTP API, data validation, LLM abstraction, and monitoring across all Onyx components.

Key dependencies specified at lines 11-30 of [`pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/pyproject.toml) include:

- **FastAPI** (`fastapi==0.133.1`) – HTTP API framework
- **Pydantic** (`pydantic==2.11.7`) – Data validation and settings management
- **Uvicorn** (`uvicorn==0.35.0`) – ASGI server implementation
- **Litellm** (`litellm==1.81.6`) – Unified LLM provider interface
- **OpenAI SDK** (`openai==2.14.0`) – Direct OpenAI API client
- **Alternative LLM clients** – Cohere, Google-GenAI, VoyageAI, and Claude-Agent-SDK
- **Observability** – Prometheus client (`prometheus_client`), FastAPI instrumentator (`prometheus_fastapi_instrumentator`), and Sentry SDK (`sentry-sdk==2.14.0`)
- **Infrastructure utilities** – `aioboto3`, `retry`, `brotli`, `discord-py`, and `kubernetes`

## Backend-Specific Dependencies

Installing the **backend** extra (lines 33-134) adds the full service stack required to run Onyx as an Enterprise Search platform. This group includes database adapters, task queues, authentication helpers, and document processing libraries.

### Database and Task Queue

- **Async PostgreSQL** – `asyncpg` for async database connections
- **SQLAlchemy** – `SQLAlchemy[mypy]` for ORM and type checking
- **Psycopg2** – `psycopg2-binary` for PostgreSQL connectivity
- **Celery** – `celery==5.5.1` with `celery-types` for distributed task processing

### Connectors and Authentication

- **Enterprise connectors** – Atlassian, Confluence, Jira, Azure Speech, Google APIs, Dropbox, HubSpot, Salesforce, and Slack SDKs
- **Authentication** – `fastapi-users`, `fastapi-limiter`, `python3-saml`, and `msal` for identity management

### Search and Document Processing

- **Search backends** – `opensearch-py` for vector search
- **Document extraction** – `unstructured` and `trafilatura` for HTML parsing
- **File format support** – `beautifulsoup4`, `lxml`, `openpyxl`, `python-docx`, and `pypdf` for parsing diverse document types
- **Caching and HTTP** – `redis`, `httpx`, `requests`, and `psutil`

## Model Server Dependencies

The **model_server** extra (lines 84-91) isolates heavy ML libraries needed only when hosting your own embedding models or LLM inference endpoints. This separation keeps the main backend lightweight when you use external API-based models.

Key ML dependencies include:

- **PyTorch** (`torch==2.9.1`) – Core tensor computation library
- **Transformers** (`transformers==4.53.0`) – HuggingFace model wrappers for loading LLMs
- **Sentence-Transformers** – Embedding model implementations
- **Performance libraries** – `accelerate`, `einops`, `safetensors`, and `numpy`

## Development and Enterprise Extras

### Development Dependencies

The **dev** extra (lines 136-175) supplies the contributor toolchain:

- **Linting and formatting** – `black`, `ruff`, and `pre-commit`
- **Static typing** – `mypy`, `basedpyright`, and `types-*` stub packages
- **Testing** – `pytest`, `pytest-asyncio`, `pytest-playwright`, and `playwright`
- **Utilities** – `matplotlib`, `faker`, `ipykernel`, and `release-tag`

### Enterprise Edition Dependencies

The **ee** extra (lines 78-80) adds a single optional package for product analytics:

- **PostHog** (`posthog==3.7.4`) – Telemetry and analytics for Enterprise Edition deployments

## How to Install Onyx Dependency Groups

Use pip extras syntax to select specific groups. The package name is `onyx` as declared in the root [`pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/pyproject.toml).

Install only the core libraries:

```bash
pip install onyx

```

Install core plus backend services (typical production deployment):

```bash
pip install "onyx[backend]"

```

Install core plus model server (required for self-hosted embeddings):

```bash
pip install "onyx[model_server]"

```

Install backend and development tools for local contribution:

```bash
pip install "onyx[backend,dev]"

```

Install Enterprise Edition features:

```bash
pip install "onyx[backend,ee]"

```

For monorepo development using UV:

```bash
uv sync

```

This command respects the optional groups defined in [`pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/pyproject.toml) and installs workspace dependencies as specified in [`backend/pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/backend/pyproject.toml).

## Key Source Files for Dependency Management

Understanding the following files helps trace how Onyx loads and uses these libraries at runtime:

- **[`pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/pyproject.toml)** (root) – Central declaration of all dependency groups and build configuration; contains the five extras groups at lines 11-175
- **[`backend/pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/backend/pyproject.toml)** – Workspace-level configuration defining the backend sub-package location
- **[`AGENTS.md`](https://github.com/onyx-dot-app/onyx/blob/main/AGENTS.md)** – High-level architecture overview explaining how workers and services split dependencies
- **[`contributing_guides/dev_setup.md`](https://github.com/onyx-dot-app/onyx/blob/main/contributing_guides/dev_setup.md)** – Detailed environment setup instructions specifying which extras to install for development
- **[`backend/onyx/server/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/main.py)** – Runtime entry point demonstrating how FastAPI, Pydantic, and other core libraries are imported and initialized

## Summary

- Onyx splits **dependencies for Onyx** into five optional groups in the root [`pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/pyproject.toml): core, backend, model_server, dev, and ee.
- **Core** dependencies (FastAPI 0.133.1, Pydantic 2.11.7, Uvicorn 0.35.0, Litellm 1.81.6) are always installed and provide the API framework, LLM abstraction, and monitoring.
- **Backend** extras add database adapters (asyncpg, SQLAlchemy), Celery 5.5.1 for task queues, and connector SDKs for enterprise data sources.
- **Model Server** extras include PyTorch 2.9.1 and Transformers 4.53.0 for self-hosted embedding and inference workloads.
- **Dev** extras provide the testing and linting toolchain (black, ruff, mypy, pytest), while **EE** extras add PostHog 3.7.4 for analytics.
- Install specific combinations using pip extras syntax (e.g., `pip install "onyx[backend,dev]"`) or use `uv sync` for monorepo development.

## Frequently Asked Questions

### What is the difference between core and backend dependencies for Onyx?

**Core dependencies** provide the shared foundation used by every Onyx component, including the HTTP server (FastAPI), data validation (Pydantic), and LLM client libraries (Litellm, OpenAI SDK). **Backend dependencies** extend this with service-specific libraries like Celery 5.5.1 for task queues, asyncpg for PostgreSQL, and connector SDKs for enterprise data sources. You need backend extras to run the full Onyx application stack, while core alone only provides the base libraries.

### Do I need the model_server dependencies to run Onyx?

No. The **model_server** extra is only required if you host your own embedding models or LLM inference endpoints using PyTorch 2.9.1 and Transformers 4.53.0. If you use external API providers like OpenAI, Anthropic, or Cohere, the core and backend groups provide sufficient LLM connectivity through Litellm 1.81.6, and you can omit the heavy ML stack to reduce container size and startup time.

### Which dependencies are required for Onyx development?

Install the **dev** extra alongside the backend group to obtain the full development toolchain. This includes `black` and `ruff` for code formatting, `mypy` and `basedpyright` for static type checking, `pytest` and `playwright` for testing, and `pre-commit` for git hooks. The root [`pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/pyproject.toml) declares these at lines 136-175, and [`contributing_guides/dev_setup.md`](https://github.com/onyx-dot-app/onyx/blob/main/contributing_guides/dev_setup.md) documents the specific installation steps.

### How do I install only the Enterprise Edition features?

Enable the **ee** extra (lines 78-80 of [`pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/pyproject.toml)) by installing `onyx[ee]`. This adds PostHog 3.7.4 for product analytics and telemetry. Typically, you combine this with the backend group using `pip install "onyx[backend,ee]"` to ensure the core application functionality is available alongside the Enterprise Edition monitoring capabilities.