dbt docs serve starts a local web server that renders interactive documentation for your compiled dbt project.
dbt docs serve is a CLI sub-command that spins up a lightweight local web server to display the auto-generated documentation for your compiled dbt project. The server bundles model lineage graphs, column metadata, and test status into an interactive UI that opens in your browser.
dbt docs generate creates static HTML files, but it does not serve them. dbt docs serve adds a transient HTTP server so you can explore docs instantly without moving files to a host. This speeds up review cycles and encourages frequent documentation checks during development.
Run the following from your project root after compiling your models:
dbt docs serve --port 8081 --profiles-dir ~/.dbt
The command builds docs (if they don’t exist) and serves them at https://localhost:8081 by default, then opens your default browser.
Yes—use --port and --host flags. Example: dbt docs serve --host 0.0.0.0 --port 9000. This is useful inside Docker or remote development environments.
The command first calls dbt docs generate to compile manifest.json and HTML assets in target/. It then launches a simple Flask app that reads those assets and exposes endpoints for search, lineage, and static files.
Press Ctrl+C in the terminal where dbt docs serve is running. The process ends, freeing the port and shutting down the Flask app.
Many teams add dbt docs generate in CI to publish static docs to S3 or Netlify. Use dbt docs serve only for local exploration or ephemeral review apps because it stores nothing persistently.
Galaxy users can map the running dbt docs port to the Galaxy desktop app via Open URL. This lets developers jump from a SQL query to model lineage in one click, enabling a seamless debugging loop.
Compile models first to avoid long startup times. Allocate a consistent port across projects to simplify browser bookmarks. Version-lock dbt to keep generated docs schemas compatible with your project.
Port conflicts—choose an unused port. Missing manifest—run dbt run or dbt compile before serving. Long load times—exclude large seeds from docs by tagging them exposure: false.
# preview_docs.sh
set -e
PROJECT_DIR=$(pwd)
dbt compile --project-dir "$PROJECT_DIR"
dbt docs serve --port 8082 --open-browser
This bash script compiles models and serves docs on port 8082 with auto-open.
Reliable documentation accelerates debugging and onboarding. dbt docs serve lowers the activation energy by hosting docs locally, encouraging engineers to document and validate models every development cycle. Quick lineage visibility reduces query errors and technical debt.
No. It is meant for local or ephemeral environments. For production, host the static files generated by `dbt docs generate` in a CDN or object store.
The command respects your OS default browser. Change that setting at the OS level or pass `BROWSER` environment variable on Unix-like systems.
Yes. Galaxy detects model names in your SQL and offers a "View in dbt Docs" shortcut that opens the served URL at the model anchor, streamlining investigation.
No. You must stop and restart the command after re-compiling models to see updates.
.png)
.avif){kind=logo}
