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

Onyx declares all runtime requirements in the top-level 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. 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 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 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.

Install only the core libraries:

pip install onyx

Install core plus backend services (typical production deployment):

pip install "onyx[backend]"

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

pip install "onyx[model_server]"

Install backend and development tools for local contribution:

pip install "onyx[backend,dev]"

Install Enterprise Edition features:

pip install "onyx[backend,ee]"

For monorepo development using UV:

uv sync

This command respects the optional groups defined in pyproject.toml and installs workspace dependencies as specified in 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 (root) – Central declaration of all dependency groups and build configuration; contains the five extras groups at lines 11-175
• backend/pyproject.toml – Workspace-level configuration defining the backend sub-package location
• AGENTS.md – High-level architecture overview explaining how workers and services split dependencies
• contributing_guides/dev_setup.md – Detailed environment setup instructions specifying which extras to install for development
• 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: 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 declares these at lines 136-175, and 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}