Install with pip

DocsGPT is on PyPI as docsgpt: the API server, the web UI, the Celery worker and the maintenance scripts in one package, behind a single docsgpt command. Use it when you want DocsGPT inside your own Python environment or process manager rather than the Docker images.

Requirements

• Python 3.12 or newer
• PostgreSQL for user data, with the vector extension if you set VECTOR_STORE=pgvector
• Redis for the task queue and the cache
• An LLM: an API key for a hosted provider, or a local model server

Install

python -m venv .venv && source .venv/bin/activate
pip install docsgpt

Extras add the optional engines:

pip install "docsgpt[docling]"   # DOC_PARSER_ENGINE=docling: OCR backend, structured output
pip install "docsgpt[milvus]"    # VECTOR_STORE=milvus
pip install "docsgpt[decisions-torch]"  # the decision model on a GPU: docsgpt decide-server --device mps

The docling extra pulls in PyTorch, and on Linux the PyPI torch wheels bring the CUDA stack with them. On a CPU-only machine install the CPU build first, then the extra; pip keeps the torch it already has:

pip install --index-url https://download.pytorch.org/whl/cpu torch torchvision
pip install "docsgpt[docling]"

uv pip install accepts the same two commands. With pipx, install docsgpt[docling] first, then replace the CUDA build inside its environment (--no-deps keeps pip from touching torch’s dependencies, which the PyTorch index carries in older copies):

pipx runpip docsgpt install --force-reinstall --no-deps --index-url https://download.pytorch.org/whl/cpu torch torchvision

Configure

DocsGPT keeps its runtime files in a data home: the .env file it reads settings from, uploaded files under inputs/, vector indexes under indexes/ and downloaded embedding models under models/. The data home is ~/.docsgpt/server (/opt/docsgpt when you run as root on Linux), whatever directory you run the commands from. DOCSGPT_HOME moves it, and DOCSGPT_ENV_FILE points at a .env kept somewhere else. Both variables must be set in the process environment, not in .env: they decide where .env is read from. In a source checkout the data home is the checkout.

Create a .env in the data home. The minimum for a hosted LLM:

# LLM provider and model: see Models > Cloud Providers for the options
LLM_PROVIDER=openai
LLM_NAME=<model id from the catalog, e.g. gpt-5.5; optional>
API_KEY=<provider API key>
 
# User data
POSTGRES_URI=postgresql://docsgpt:<password>@localhost:5432/docsgpt
 
# Worker-to-API authentication (required for uploads)
INTERNAL_KEY=<a long random string>

Redis defaults to localhost:6379 (CELERY_BROKER_URL, CELERY_RESULT_BACKEND, CACHE_REDIS_URL). Every setting is listed in App Configuration.

Run

docsgpt migrate    # create the database if it is missing and apply the migrations
docsgpt api        # the API and the web UI on http://127.0.0.1:7091
docsgpt worker     # in a second terminal: the Celery worker, with the scheduler

docsgpt api listens on localhost only. Pass --host 0.0.0.0 to accept connections from other machines or containers, and put a reverse proxy with TLS in front of it for anything public.

When other machines open DocsGPT, set API_URL in .env to the address they use (for example https://docs.example.com): the API builds agent image, webhook, device pairing and MCP OAuth callback links from it. The worker reads the same .env and would then send its own calls to the API through that public address, so also set WORKER_API_URL=http://127.0.0.1:7091 to keep them on this machine.

The API applies pending migrations when it starts (AUTO_MIGRATE), so docsgpt migrate is the explicit step for deployments that want the schema in place before the first request or that run the API with a restricted database role.

Both commands print the data home they resolved on start-up. They share it as long as DOCSGPT_HOME is the same for both (or unset), so the worker finds the files the API stores and the API finds the indexes the worker builds.

The worker is not optional: query embedding runs on it, so search fails without one. docsgpt worker --help lists the queue, concurrency and pool options; --no-beat starts a worker without the scheduler when another worker already runs it. On Windows the scheduler cannot be embedded, so run docsgpt beat in a third terminal.

Other commands include docsgpt api --reload (a development server with auto-reload), docsgpt prefetch-models and docsgpt verify-offline (for machines that go offline, see Air-Gapped Deployment), docsgpt reembed (after changing EMBEDDINGS_NAME) and docsgpt grant-admin (the first admin under OIDC). The docsgpt CLI reference lists them all.

Run it as services, without Docker

docsgpt up --native runs the API and the worker as services on the machine itself: launchd agents on macOS, systemd user units on Linux. It does not start PostgreSQL or Redis; point it at ones you already run.

docsgpt up --native \
  --postgres-uri postgresql://docsgpt:<password>@localhost:5432/docsgpt \
  --redis-url redis://localhost:6379

Without a terminal only --postgres-uri is required, since Redis defaults to redis://localhost:6379; with one, it asks for both and for the model provider. It writes the same .env a Docker install uses (minus the image settings), generates INTERNAL_KEY and JWT_SECRET_KEY on the first run, applies the migrations, then starts docsgpt-api and docsgpt-worker and waits for the API to answer.

One Redis URL covers all three uses: the Celery broker, its result backend and the cache go on databases 0, 1 and 2 of it. Name a database in the URL and the three start there instead, so redis://localhost:6379/5 puts them on 5, 6 and 7 — that is how you share a Redis that already holds something else.

The same commands manage it:

docsgpt up --native sets API_URL and WORKER_API_URL to http://127.0.0.1:<port>. Behind a reverse proxy, change API_URL to the public address with docsgpt env set API_URL=https://docs.example.com; later runs keep it, and WORKER_API_URL keeps the worker on loopback.

uninstall never touches the database or Redis: they were yours to begin with. docsgpt restart, docsgpt env set and docsgpt doctor work in native mode too; see the CLI reference.

Upgrade

pip install -U docsgpt
docsgpt migrate

Read the upgrade notes first when moving between minor versions.