How to Use dbt docs serve to View Project Documentation

Use dbt docs serve to start a local web server that displays your dbt project's documentation in a browser. This command serves the docs generated by dbt docs generate and lets you explore models, sources, and lineage interactively.

Syntax

The basic syntax of dbt docs serve is simple and requires no arguments. It starts a local web server to serve your project's documentation.

• dbt docs serve: Launches the docs server on the default port (usually 8080).
• You can optionally specify a port with --port <port_number>.

bash

dbt docs serve [--port <port_number>]

Example

This example shows how to generate your dbt docs and then serve them locally to view in a browser.

bash

dbt docs generate
# This creates the documentation files

dbt docs serve
# This starts a local server and opens the docs in your browser

Output

Serving docs at http://localhost:8080
Press Ctrl+C to stop.

Common Pitfalls

Some common mistakes when using dbt docs serve include:

• Trying to serve docs before running dbt docs generate, which means no docs are available to serve.
• Port conflicts if the default port 8080 is already in use.
• Not having a valid target profile or connection, so docs generation fails silently.

Always run dbt docs generate first and check for errors before serving.

bash

## Wrong: Serving docs without generating
# dbt docs serve
# This will fail or show empty docs

## Right: Generate then serve
# dbt docs generate
# dbt docs serve

Quick Reference

Here is a quick summary of the dbt docs serve command options and usage tips.

Command	Description
dbt docs generate	Generate the documentation files for your project
dbt docs serve	Start a local server to view the docs in a browser
dbt docs serve --port 9090	Serve docs on port 9090 instead of default 8080
Ctrl+C	Stop the docs server

Key Takeaways

Always run dbt docs generate before dbt docs serve to create documentation files.

dbt docs serve starts a local web server to view your dbt docs in a browser.

You can specify a custom port with --port if the default port is busy.

Press Ctrl+C in the terminal to stop the docs server when done.

Check your dbt project connection and profiles to ensure docs generate correctly.