This document provides instructions for setting up a local development environment for contributing to DB-GPT. It covers prerequisite software installation, repository setup, dependency management using the uv package manager, and IDE configuration.
For information about the project structure and build system, see Project Structure and Build System. For information about testing your changes, see Testing and Quality Assurance.
DB-GPT requires Python 3.10 or higher. The project uses uv as its package manager for fast dependency resolution and installation.
| Requirement | Minimum Version | Notes |
|---|---|---|
| Python | 3.10 | Maximum tested: 3.13 |
| Operating System | Linux, macOS, Windows | Full support on all platforms |
| Memory | 8 GB RAM | 16 GB+ recommended for model development |
| Disk Space | 10 GB | More required for models and datasets |
Sources: packages/dbgpt-core/pyproject.toml13 pyproject.toml13
While not required, using a Python version manager is recommended for managing multiple Python versions:
The .gitignore file excludes virtual environment directories (.venv/, venv/, env/) to prevent accidental commits.
Sources: .gitignore96-123
DB-GPT uses uv as its package manager, which provides significantly faster dependency resolution and installation compared to traditional pip.
Linux and macOS:
Windows (PowerShell):
Using pip (all platforms):
Using pipx:
Verify installation:
Sources: Referenced from standard uv installation practices
Clone the DB-GPT repository from GitHub:
DB-GPT uses a monorepo structure with seven distinct packages managed through a workspace configuration. Understanding this structure is essential for development.
The workspace is configured in the root pyproject.toml:
Sources: pyproject.toml31-40 packages/dbgpt-core/pyproject.toml1-13 packages/dbgpt-ext/pyproject.toml1-10 packages/dbgpt-app/pyproject.toml1-10
Create and activate a virtual environment using uv:
The virtual environment is automatically excluded from version control by .gitignore.
Sources: .gitignore116-123
DB-GPT supports multiple installation modes through optional dependencies. The dependency graph below illustrates the relationship between installation modes:
Minimal installation (development dependencies only):
Full installation with all development dependencies:
Install specific package with extras:
Sources: packages/dbgpt-core/pyproject.toml34-162 packages/dbgpt-ext/pyproject.toml27-88 packages/dbgpt-app/pyproject.toml32-48 pyproject.toml42-60
For GPU acceleration and model inference, install the appropriate acceleration package based on your hardware:
CUDA 11.8 (NVIDIA GPUs):
CUDA 12.1 (NVIDIA GPUs):
CUDA 12.4 (Latest NVIDIA GPUs):
Apple Silicon (macOS):
CPU Only:
Auto-detect (recommended for most users):
The acceleration package uses custom PyTorch indexes configured in the pyproject.toml:
Sources: packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml26-103 packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml125-196
Install optional storage backends and datasource connectors as needed:
| Extra | Purpose | Key Dependencies |
|---|---|---|
rag | Document processing for RAG | spacy, pypdf, pdfplumber, bs4 |
graph_rag | Knowledge graph RAG | networkx, dbgpt-tugraph-plugins, neo4j |
storage_milvus | Milvus vector store | pymilvus |
storage_chromadb | ChromaDB vector store | chromadb>=0.4.22, onnxruntime |
storage_elasticsearch | Elasticsearch vector store | elasticsearch |
storage_weaviate | Weaviate vector store | weaviate-client |
datasource_mysql | MySQL connector | mysqlclient==2.1.0 |
datasource_postgres | PostgreSQL connector | psycopg2-binary |
datasource_clickhouse | ClickHouse connector | clickhouse-connect |
datasource_oracle | Oracle connector | oracledb==3.1.0 |
Example installations:
Sources: packages/dbgpt-ext/pyproject.toml27-88
The package configuration defines conflicts between certain extras that cannot be installed together. These are enforced through uv's conflict resolution:
Sources: packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml110-118 packages/dbgpt-core/pyproject.toml176-193
After installation, verify that the packages are correctly installed:
All packages should be at version 0.7.5:
Sources: packages/dbgpt-core/src/dbgpt/_version.py1 packages/dbgpt-ext/src/dbgpt_ext/_version.py1 packages/dbgpt-app/src/dbgpt_app/_version.py1 packages/dbgpt-client/src/dbgpt_client/_version.py1 packages/dbgpt-serve/src/dbgpt_serve/_version.py1
Create or update .vscode/settings.json in the project root:
Install recommended VSCode extensions:
charliermarsh.ruff): Python linter and formatterms-python.python): Python language supportms-python.mypy-type-checker): Static type checkingThe .gitignore file excludes .vscode directories to prevent IDE-specific settings from being committed.
Sources: .gitignore10 pyproject.toml68-86
Configure Python Interpreter:
.venv/bin/python (or .venv\Scripts\python.exe on Windows)Configure Source Roots:
src directorypackages/Configure Testing:
pytest--import-mode=importlibThe .gitignore file excludes .idea directories to prevent IDE-specific settings from being committed.
Sources: .gitignore11 .gitignore165 pyproject.toml63-66
The uv.lock file ensures reproducible builds across all environments. It contains resolved dependencies for all platforms and Python versions:
Key commands:
Sources: uv.lock1-10 uv.lock4-44
Install pre-commit hooks for automatic code quality checks:
Sources: pyproject.toml58
DB-GPT uses mypy for static type checking:
Sources: pyproject.toml59
Work on specific packages in isolation:
Add to appropriate pyproject.toml:
Update lock file:
Sync dependencies:
Issue: Import errors after installation
Issue: CUDA version mismatch
Issue: Build isolation errors (e.g., gptqmodel)
Some packages like gptqmodel require disabling build isolation:
Sources: packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml194-196
After setting up your development environment:
Sources: Contextual references to other wiki sections
Refresh this wiki