LangGraph.json Configuration Reference

LangGraph.json Configuration Reference

Complete reference for the langgraph.json configuration file.

Overview

The langgraph.json file specifies dependencies, graphs, environment variables, and other settings required to deploy a LangGraph application. The LangGraph CLI uses this file to build and run your application.

Required Fields

dependencies

Type: array of strings Required: Yes

Array of dependencies for the application. Can be:

• "." - Current directory (looks for pyproject.toml, setup.py, requirements.txt, or package.json)
• "./path" - Relative path to a directory with package configuration
• "package-name" or "package-name==1.0.0" - Package name (optionally with version)

Examples:

{
  "dependencies": ["."]
}

{
  "dependencies": ["./my_package", "langchain==0.3.0"]
}

graphs

Type: object (string → string mapping) Required: Yes

Mapping from graph ID to path where the compiled graph or factory function is defined.

Format: ./path/to/file.{py|js|ts}:variable or package.module:variable

Where variable is either:

• An instance of CompiledStateGraph
• A function that returns a StateGraph or CompiledStateGraph

Examples:

{
  "graphs": {
    "agent": "./my_agent/agent.py:graph",
    "chatbot": "./my_agent/chatbot.py:create_graph"
  }
}

Optional Fields

env

Type: string (path) or object (key-value pairs) Default: None

Path to .env file or direct environment variable definitions.

Examples:

{
  "env": ".env"
}

{
  "env": {
    "MY_VAR": "value",
    "OPENAI_API_KEY": "sk-..."
  }
}

python_version

Type: string Options: "3.11", "3.12", "3.13" Default: "3.11"

Python version to use (Python projects only).

Example:

{
  "python_version": "3.12"
}

node_version

Type: string Options: "20" Default: None (omit for Python projects)

Specifying node_version: "20" indicates a JavaScript/TypeScript project.

Example:

{
  "node_version": "20"
}

base_image

Type: string Default: "langchain/langgraph-api" (Python) or "langchain/langgraphjs-api" (JavaScript)

Base Docker image for the LangGraph API server. Use a versioned tag to pin (for example, langchain/langgraph-server:0.2).

Example:

{
  "base_image": "langchain/langgraph-server:0.2"
}

image_distro

Type: string Options: "debian", "wolfi", "bookworm", "bullseye" Default: "debian" Minimum CLI version: 0.2.11

Linux distribution for the base image.

Example:

{
  "image_distro": "wolfi"
}

pip_installer

Type: string Options: "auto", "pip", "uv" Default: "auto" (uses uv if available) Minimum CLI version: 0.3.0

Python package installer to use.

Example:

{
  "pip_installer": "uv"
}

pip_config_file

Type: string Default: None

Path to pip configuration file.

Example:

{
  "pip_config_file": "./pip.conf"
}

keep_pkg_tools

Type: boolean or array of strings Options: true, false, or array with ["pip", "setuptools", "wheel"] Default: false (uninstall all) Minimum CLI version: 0.3.4

Controls whether to retain Python packaging tools in the final image.

Example:

{
  "keep_pkg_tools": ["pip", "setuptools"]
}

dockerfile_lines

Type: array of strings Default: []

Additional Dockerfile lines to add after the base image import.

Example:

{
  "dockerfile_lines": [
    "RUN apt-get update && apt-get install -y postgresql-client",
    "ENV CUSTOM_VAR=value"
  ]
}

checkpointer

Type: object Default: None

Configuration for the checkpointer (state persistence).

Sub-fields:

• ttl: Object with strategy, sweep_interval_minutes, default_ttl
• serde (v0.5+): Object with allowed_json_modules and pickle_fallback

Example:

{
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 60,
      "default_ttl": 1440
    },
    "serde": {
      "allowed_json_modules": ["my_module"],
      "pickle_fallback": true
    }
  }
}

store

Type: object Default: None

Configuration for semantic search and TTL in BaseStore.

Sub-fields:

• index: Configuration for semantic search
  • embed: Embedding model configuration
  • dims: Embedding dimensions
  • fields: Fields to index
• ttl: Time-to-live configuration
  • refresh_on_read: Boolean (default: true)
  • default_ttl: Float (minutes)
  • sweep_interval_minutes: Integer

Example:

{
  "store": {
    "index": {
      "embed": "openai:text-embedding-3-small",
      "dims": 1536,
      "fields": ["$"]
    },
    "ttl": {
      "default_ttl": 60,
      "sweep_interval_minutes": 10
    }
  }
}

http

Type: object Default: None

HTTP server configuration.

Sub-fields:

• app: Path to custom Starlette/FastAPI app
• cors: CORS configuration
• configurable_headers: Define which headers to expose
• logging_headers: Exclude sensitive headers from logs
• middleware_order: "auth_first" or "middleware_first" (default)
• enable_custom_route_auth: Apply auth to custom routes
• disable_*: Disable built-in routes (disable_a2a, disable_assistants, disable_mcp, disable_runs, disable_store, disable_threads, disable_ui, disable_webhooks, disable_meta)
• mount_prefix: Prefix for mounted routes

Example:

{
  "http": {
    "cors": {
      "allow_origins": ["https://example.com"],
      "allow_methods": ["GET", "POST"],
      "allow_credentials": true
    },
    "configurable_headers": {
      "includes": ["x-user-id"],
      "excludes": ["authorization"]
    }
  }
}

webhooks

Type: object Default: None Minimum CLI version: 0.5.36

Configuration for outbound webhook delivery.

Sub-fields:

• env_prefix: Required prefix for env vars (default: "LG_WEBHOOK_")
• headers: Static headers for webhooks
• url: URL validation policy (allowed_domains, allowed_ports, require_https, disable_loopback, max_url_length)

Example:

{
  "webhooks": {
    "env_prefix": "LG_WEBHOOK_",
    "headers": {
      "X-Custom-Header": "${{ env.HEADER_VALUE }}"
    },
    "url": {
      "require_https": true,
      "disable_loopback": true
    }
  }
}

auth

Type: object Default: None Minimum CLI version: 0.0.11

Authentication configuration. path uses format ./path/to/auth.py:auth.

Example:

{
  "auth": {
    "path": "./my_agent/auth.py:auth"
  }
}

ui

Type: object Default: None Minimum CLI version: 0.1.84

Named definitions of UI components emitted by the agent.

Example:

{
  "ui": {
    "my_component": "./ui/component.js"
  }
}

api_version

Type: string Default: Latest Minimum CLI version: 0.3.7

Semantic version of the LangGraph API server to use.

Example:

{
  "api_version": "0.3"
}

Complete Example

Python Project

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./my_agent/agent.py:graph"
  },
  "env": ".env",
  "python_version": "3.11",
  "pip_installer": "uv",
  "checkpointer": {
    "ttl": {
      "default_ttl": 1440
    }
  },
  "http": {
    "cors": {
      "allow_origins": ["*"],
      "allow_methods": ["GET", "POST", "PUT", "DELETE"]
    }
  }
}

JavaScript Project

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/agent.ts:graph"
  },
  "env": ".env",
  "node_version": "20",
  "http": {
    "cors": {
      "allow_origins": ["*"]
    }
  }
}

Validation

Use the provided validation script to check your configuration:

uv run scripts/validate_langgraph_config.py

# Fallback if uv not available
python3 scripts/validate_langgraph_config.py

References

• LangGraph CLI Documentation
• Application Structure Guide