Installation Guide

QuantumEngine uses a modular installation system that allows you to install only the backends you need, keeping your environment lightweight and efficient.

Installation Options

Core Package (Minimal)

pip install quantumengine

Includes: Core ORM functionality, field types, query building Size: ~5MB Use Case: When you want to use only specific backends or aren’t sure which backends you’ll need

Backend-Specific Installations

ClickHouse Only

pip install quantumengine[clickhouse]

Includes: Core + ClickHouse backend + clickhouse-connect Use Case: Data analytics, time-series data, high-performance aggregations

SurrealDB Only

pip install quantumengine[surrealdb]

Includes: Core + SurrealDB backend + surrealdb package Use Case: Graph databases, document storage, real-time applications

Multiple Backends

pip install quantumengine[clickhouse,surrealdb]

Includes: Core + both backends Use Case: Multi-database applications, data pipeline systems

Development Installation

pip install quantumengine[dev]

Includes: Core + testing tools (pytest, mypy, black, ruff) Use Case: Contributing to QuantumEngine or extensive development

Complete Installation

pip install quantumengine[all]

Includes: Everything (all backends + development tools) Use Case: Full-featured development environment

Installation Size Comparison

Installation Type

Download Size

Disk Size

Dependencies

quantumengine

~1MB

~5MB

1 (typing-extensions)

quantumengine[clickhouse]

~15MB

~45MB

+clickhouse-connect

quantumengine[surrealdb]

~8MB

~25MB

+surrealdb

quantumengine[all]

~20MB

~65MB

All backends

Checking Available Backends

You can check which backends are available in your environment:

from quantumengine.backends import BackendRegistry

# List successfully loaded backends
print("Available backends:", BackendRegistry.list_backends())

# List backends with missing dependencies
print("Failed backends:", BackendRegistry.list_failed_backends())

# Check if specific backend is available
if BackendRegistry.is_backend_available('clickhouse'):
    print("ClickHouse backend is ready!")
else:
    print("ClickHouse backend needs installation")

Troubleshooting

Missing Backend Dependencies

If you see an error like:

ImportError: ClickHouse backend requires the 'clickhouse-connect' package.
Install it with: pip install quantumengine[clickhouse]

Solution: Install the backend-specific package:

pip install quantumengine[clickhouse]
# or
pip install quantumengine[surrealdb]

Import Errors

If you get import errors for specific backends:

# This will show you exactly what's missing
from quantumengine.backends import BackendRegistry
failed = BackendRegistry.list_failed_backends()
for backend, error in failed.items():
    print(f"{backend}: {error}")

Version Conflicts

If you experience dependency conflicts:

# Upgrade to latest versions
pip install --upgrade quantumengine[all]

# Or install in a clean environment
python -m venv quantumengine_env
source quantumengine_env/bin/activate  # On Windows: quantumengine_env\\Scripts\\activate
pip install quantumengine[all]

Docker Installation

For containerized deployments, you can use the modular installation in your Dockerfile:

# Minimal ClickHouse-only container
FROM python:3.11-slim
RUN pip install quantumengine[clickhouse]
COPY . /app
WORKDIR /app

# Or multi-backend container
FROM python:3.11-slim
RUN pip install quantumengine[all]
COPY . /app
WORKDIR /app