Installation

This guide covers installing detectkit and its dependencies.

Requirements

• Python: 3.10 or higher
• pip: Latest version recommended
• Database: ClickHouse (20.3+), PostgreSQL (12+), or MySQL (8.0+) — all fully supported

Basic Installation

Install detectkit from PyPI:

pip install detectkit

This installs:

• Core detectkit library
• Basic statistical detectors (MAD, Z-Score, IQR, Manual Bounds)
• CLI tool (dtk command)
• numpy, pydantic, click dependencies

Database Drivers

detectkit requires a database driver to be installed separately.

ClickHouse (Recommended)

pip install detectkit[clickhouse]

Or install driver manually:

pip install clickhouse-driver

Supported versions: ClickHouse 20.3+

PostgreSQL

pip install detectkit[postgres]

Or install driver manually:

pip install psycopg2-binary

Supported versions: PostgreSQL 12+. See the PostgreSQL guide for the profile shape.

MySQL

pip install detectkit[mysql]

Or install driver manually:

pip install pymysql

Supported versions: MySQL 8.0+. See the MySQL guide for the profile shape.

Multiple Databases

Install drivers for all databases you’ll use:

pip install detectkit[clickhouse,postgres,mysql]
# or the shorthand:
pip install detectkit[all-db]

Advanced Detectors (Optional)

Not yet implemented. The prophet and timesfm extras install the underlying libraries, but detectkit does not ship Prophet or TimesFM detector classes yet — the only detector type:s that exist today are the statistical detectors (mad, zscore, iqr) and manual_bounds. These extras are placeholders for planned detectors; installing them adds the dependencies but no new detector. Track progress in the changelog before relying on them.

Prophet Detector (planned)

Time-series forecasting with Facebook Prophet (extra reserved; detector not yet available):

pip install detectkit[prophet]

Note: Prophet has heavy dependencies (compiled Stan backend). Only install if needed.

TimesFM Detector (planned)

Google’s TimesFM model for time-series (extra reserved; detector not yet available):

pip install detectkit[timesfm]

Note: Pulls in heavy ML dependencies. Only install if needed.

All Advanced Detectors

Install both Prophet and TimesFM (no database drivers):

pip install detectkit[advanced-detectors]

Everything

The [all] extra installs everything — all database drivers plus Prophet and TimesFM, not just the advanced detectors:

pip install detectkit[all]

Development Installation

For contributing to detectkit:

1. Clone Repository

git clone https://github.com/alexeiveselov92/detectkit.git
cd detectkit

2. Create Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install in Editable Mode

pip install -e .[dev]

This installs:

• detectkit in editable mode
• Development tooling only (pytest, pytest-cov, pytest-mock, requests-mock, black, mypy, ruff)

The dev extra does not include any database drivers. For the full suite, add the DB extras you need (and Docker-backed integration tests):

pip install -e ".[dev,all-db]"          # tooling + all DB drivers
pip install -e ".[dev,all-db,integration]"  # also pulls testcontainers for integration tests

4. Run Tests

Unit tests (no external services required):

python -m pytest tests/unit

Integration tests need the integration extra (testcontainers) and a running Docker daemon:

pip install -e ".[integration]"
python -m pytest tests/integration

Verifying Installation

Check that detectkit is installed correctly:

dtk --version

This prints the installed package version:

detectkit, version x.y.z

Optional: AI Onboarding

If you use Claude Code, dtk init-claude drops detectkit context (rules and skills) into your project so the assistant understands the project layout:

dtk init-claude

It installs three skills: dtk-setup-project (configure the database connection and a first alert channel), dtk-new-metric (scaffold a validated metric), and dtk-feedback (file a redacted bug report, feature request, or feedback as a GitHub issue upstream).

Re-run it after upgrading detectkit to refresh the shipped context.

Upgrading

Upgrade to the latest version:

pip install --upgrade detectkit

Uninstalling

Remove detectkit:

pip uninstall detectkit

Docker Installation (Optional)

Create a Dockerfile for containerized deployment:

FROM python:3.11-slim

# Install detectkit with ClickHouse driver
RUN pip install detectkit[clickhouse]

# Copy project files
COPY . /app
WORKDIR /app

# Run detectkit
CMD ["dtk", "run", "--select", "*"]

Build and run:

docker build -t my-detectkit .
docker run -v $(pwd):/app my-detectkit

Troubleshooting

ImportError: No module named ‘detectkit’

Solution: Ensure detectkit is installed in the active Python environment:

pip list | grep detectkit

ClickHouse driver not found

Solution: Install ClickHouse driver:

pip install clickhouse-driver

Permission denied on Linux

Solution: Install with —user flag:

pip install --user detectkit

SSL certificate errors

Solution: Upgrade pip and certifi:

pip install --upgrade pip certifi

Old version installed

Solution: Force reinstall:

pip install --force-reinstall detectkit

Next Steps

After installation:

1. Quickstart Guide - Create your first metric
2. Configuration Guide - Learn configuration options
3. CLI Reference - Explore CLI commands
4. Run dtk init-claude for optional Claude Code onboarding (re-run after upgrades)

Getting Help

• Documentation: https://github.com/alexeiveselov92/detectkit
• Issues: https://github.com/alexeiveselov92/detectkit/issues
• PyPI: https://pypi.org/project/detectkit/