Implementation:Langchain ai Langgraph Langgraph Build Command

Property	Value
API	`langgraph build` CLI command and `config_to_docker` function
Type	External Tool Doc + API Doc
Source	`libs/cli/langgraph_cli/cli.py` and `libs/cli/langgraph_cli/config.py`
Library	langgraph-cli
Related Workflow	CLI_Deployment

Overview

The `langgraph build` command builds a production-ready Docker image from a LangGraph project configuration. It validates the configuration file, optionally pulls the latest base image, generates a Dockerfile via the `config_to_docker` function, and invokes `docker build` to create the tagged image. The `config_to_docker` function is the internal API responsible for translating the declarative configuration into a complete Dockerfile string.

Description

langgraph build Command

The `build` command is registered as a Click subcommand at `libs/cli/langgraph_cli/cli.py:L364-430`. Its execution flow:

1. Docker check: Verifies Docker is installed via `shutil.which("docker")`.
2. Configuration validation: Calls `validate_config_file` to load and validate `langgraph.json`.
3. Distro warning: Warns if using a non-wolfi distribution.
4. Build delegation: Calls the internal `_build` helper, which:
   1. Optionally pulls the base image.
   2. Generates the Dockerfile via `config_to_docker`.
   3. Invokes `docker build` with the generated Dockerfile piped via stdin.

config_to_docker Function

The `config_to_docker` function at `libs/cli/langgraph_cli/config.py:L1210-1232` is the dispatcher that selects between Python and Node.js Dockerfile generation:

• If the config has `node_version` and no `python_version`, it delegates to `node_config_to_docker`.
• Otherwise, it delegates to `python_config_to_docker`.

Both generators return a tuple of `(dockerfile_string, additional_contexts_dict)`.

python_config_to_docker

The Python Dockerfile generator (`libs/cli/langgraph_cli/config.py:L827-1056`) performs:

1. Installer selection: Chooses between `pip` and `uv` based on `pip_installer` setting and base image compatibility.
2. Dependency assembly: Calls `_assemble_local_deps` to classify local dependencies.
3. Path rewriting: Calls `_update_graph_paths`, `_update_auth_path`, `_update_encryption_path`, and `_update_http_app_path` to translate host paths to container paths.
4. Dockerfile composition: Assembles the Dockerfile from:
   • Base image `FROM` line.
   • Custom `dockerfile_lines`.
   • PyPI package installation.
   • Local requirements installation.
   • Local package `ADD`/`COPY` instructions.
   • Faux package generation with `pyproject.toml`.
   • Editable installation of all `/deps/*` packages.
   • Environment variable `ENV` directives.
   • Optional JavaScript dependency installation.
   • Build tool cleanup.
   • Working directory setting.

Build Command Options

Option	Type	Default	Description
`--config` / `-c`	`Path`	`langgraph.json`	Path to configuration file
`--tag` / `-t`	`str`	(required)	Tag for the Docker image
`--pull` / `--no-pull`	flag	`True`	Pull latest base image before building
`--base-image`	`str`	`None`	Override default base image
`--api-version`	`str`	`None`	Pin API server version
`--install-command`	`str`	`None`	Custom install command (JS projects)
`--build-command`	`str`	`None`	Custom build command (JS projects)
passthrough args	`str...`		Additional arguments passed to `docker build`

Code Reference

Source Location

Item	File	Line
`build` command	`libs/cli/langgraph_cli/cli.py`	L364-430
`_build` helper	`libs/cli/langgraph_cli/cli.py`	L295-361
`config_to_docker`	`libs/cli/langgraph_cli/config.py`	L1210-1232
`python_config_to_docker`	`libs/cli/langgraph_cli/config.py`	L827-1056
`node_config_to_docker`	`libs/cli/langgraph_cli/config.py`	L1059-1150

Signature

# CLI command
@cli.command(help="Build LangGraph API server Docker image.")
def build(
    config: pathlib.Path,
    docker_build_args: Sequence[str],
    base_image: str | None,
    api_version: str | None,
    pull: bool,
    tag: str,
    install_command: str | None,
    build_command: str | None,
):
    ...

# Internal API
def config_to_docker(
    config_path: pathlib.Path,
    config: Config,
    *,
    base_image: str | None = None,
    api_version: str | None = None,
    install_command: str | None = None,
    build_command: str | None = None,
    build_context: str | None = None,
    escape_variables: bool = False,
) -> tuple[str, dict[str, str]]:
    ...

Import

CLI command:

langgraph build -t <tag> [OPTIONS]

Internal Python API:

from langgraph_cli.config import config_to_docker

I/O Contract

langgraph build

Direction	Name	Type	Description
Input	CLI options	various	Command-line flags (config, tag, base-image, etc.)
Input	config file	JSON	`langgraph.json` configuration
Output	Docker image	image	Tagged Docker image in local Docker daemon
Raises	`click.UsageError`		If Docker is not installed or configuration is invalid

config_to_docker

Direction	Name	Type	Description
Input	`config_path`	`pathlib.Path`	Path to the configuration file
Input	`config`	`Config`	Validated configuration dictionary
Input	`base_image`	None`	Override base image (uses default if `None`)
Input	`api_version`	None`	Pin API server version
Input	`install_command`	None`	Custom install command (JS only)
Input	`build_command`	None`	Custom build command (JS only)
Input	`build_context`	None`	Custom build context path (JS monorepos)
Input	`escape_variables`	`bool`	Escape `$` as `$$` for Docker Compose inline Dockerfiles
Output	return	`tuple[str, dict[str, str]]`	Tuple of (Dockerfile content, additional build contexts)

Usage Examples

Building a Basic Image

# Build from default langgraph.json
langgraph build -t my-langgraph-app

# Build from a specific config
langgraph build -c ./configs/prod.json -t my-app:prod

Building with Pinned Versions

# Pin the API server version
langgraph build -t my-app --api-version 0.2.18

# Use a specific base image
langgraph build -t my-app --base-image langchain/langgraph-server:0.2.18

Using config_to_docker Programmatically

import pathlib
from langgraph_cli.config import validate_config_file, config_to_docker

config_path = pathlib.Path("langgraph.json")
config = validate_config_file(config_path)

dockerfile, additional_contexts = config_to_docker(
    config_path=config_path,
    config=config,
    base_image="langchain/langgraph-api",
    api_version="0.2.18",
)

print(dockerfile)
# FROM langchain/langgraph-api:0.2.18-py3.11
# ...

Passing Docker Build Arguments

# Build for a specific platform
langgraph build -t my-app --platform linux/amd64

# Build with no cache
langgraph build -t my-app --no-cache

Related Pages

• Langchain_ai_Langgraph_Docker_Image_Building
• Environment:Langchain_ai_Langgraph_Docker_Deployment_Environment
• Langchain_ai_Langgraph_Validate_Config_File
• Langchain_ai_Langgraph_Config_Graph_Paths
• Langchain_ai_Langgraph_Langgraph_Up_Command