Configuration Reference

The langgraph.json file is the central configuration for your LangGraph application, defining dependencies, graphs, environment settings, and deployment options.

Schema

You can enable IntelliSense and validation in your editor by adding the schema reference:

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": [...],
  "graphs": {...}
}

Configuration Structure

Minimal Configuration

At minimum, you need to specify dependencies and graphs:

{
  "dependencies": ["langchain-openai", "."],
  "graphs": {
    "agent": "./src/agent.py:graph"
  }
}

Complete Example

{
  "$schema": "https://langgra.ph/schema.json",
  "python_version": "3.11",
  "dependencies": [
    "langchain-openai",
    "langchain-anthropic",
    "."
  ],
  "graphs": {
    "agent": "./src/agent.py:graph",
    "research_assistant": {
      "path": "./src/research.py:create_graph",
      "description": "Multi-agent research assistant"
    }
  },
  "env": ".env",
  "store": {
    "index": {
      "embed": "openai:text-embedding-3-large",
      "dims": 3072,
      "fields": ["title", "content"]
    }
  },
  "dockerfile_lines": [
    "RUN apt-get update && apt-get install -y libmagic-dev"
  ]
}

Core Fields

`dependencies`

Type: string[]
Required: Yes (for Python projects) List of Python packages to install. Can include:

PyPI packages: "langchain-openai"
Local packages: "." or "./my_package"
Git repositories: "git+https://github.com/org/repo.git"

Examples:

{
  "dependencies": [
    "langchain-openai",
    "langchain-anthropic",
    "wikipedia",
    "."
  ]
}

{
  "dependencies": [
    "langchain-openai>=0.1.0",
    "./packages/my-tools",
    "git+https://github.com/org/private-lib.git@main"
  ]
}

The "." dependency tells the CLI to install your local package (looks for pyproject.toml, setup.py, or requirements.txt).

`graphs`

Type: Record<string, string | GraphDef>
Required: Yes Maps graph IDs to their import paths. Each graph must point to a compiled graph object or a context manager that returns one. Format: "path/to/file.py:variable_name" Simple format:

{
  "graphs": {
    "agent": "./src/agent.py:graph",
    "chatbot": "./src/chatbot.py:chat_graph"
  }
}

Extended format with descriptions:

{
  "graphs": {
    "agent": {
      "path": "./src/agent.py:graph",
      "description": "A ReAct agent with tool calling"
    },
    "research": {
      "path": "./src/research.py:create_research_graph",
      "description": "Multi-agent research system with web search"
    }
  }
}

Valid graph objects:

StateGraph instances
CompiledGraph instances
Functions decorated with @entrypoint
Any Pregel object
Context managers that yield a graph:

from contextlib import asynccontextmanager
from langgraph.graph import StateGraph

@asynccontextmanager
async def create_graph(config):
    # Setup
    graph = StateGraph(...)
    # ... configure graph
    yield graph.compile()
    # Cleanup

`env`

Type: string | Record<string, string>
Required: No Environment variables for your application. As a file path:

{
  "env": ".env"
}

As inline values:

{
  "env": {
    "OPENAI_API_KEY": "sk-...",
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "LOG_LEVEL": "INFO"
  }
}

Do not commit API keys directly in langgraph.json. Use a .env file and add it to .gitignore.

Python Configuration

`python_version`

Type: string
Default: "3.11"
Format: "major.minor" (e.g., "3.11", "3.12", "3.13") Python version for Docker deployment. Must be 3.11 or higher.

{
  "python_version": "3.12"
}

Patch versions cannot be specified. The latest patch version of the specified minor version is used.

`pip_config_file`

Type: string
Required: No Path to a pip configuration file for custom package indices or authentication.

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

Example pip.conf:

[global]
index-url = https://pypi.org/simple
extra-index-url = https://my-private-pypi.com/simple

`pip_installer`

Type: "auto" | "pip" | "uv"
Default: "auto" Choose which package installer to use:

"auto": Use uv if base image supports it, otherwise pip
"pip": Force use of pip
"uv": Force use of uv (faster, but requires compatible base image)

{
  "pip_installer": "uv"
}

`keep_pkg_tools`

Type: boolean | string[]
Default: false Control whether to keep packaging tools (pip, setuptools, wheel) in the final image.

// Keep all tools
{
  "keep_pkg_tools": true
}

// Keep specific tools
{
  "keep_pkg_tools": ["pip"]
}

// Remove all tools (default)
{
  "keep_pkg_tools": false
}

Node.js Configuration

`node_version`

Type: string
Required: For JavaScript/TypeScript graphs
Format: Major version only (e.g., "20") Node.js version for JavaScript/TypeScript projects. Must be 20 or higher.

{
  "node_version": "20",
  "graphs": {
    "agent": "./src/agent.ts:graph"
  }
}

If your graphs use .ts, .js, .mts, or .cts extensions, Node.js support is automatically enabled.

Docker Configuration

`base_image`

Type: string
Default: "langchain/langgraph-api" (Python) or "langchain/langgraphjs-api" (Node.js) Base Docker image for your deployment.

{
  "base_image": "langchain/langgraph-api:0.2.47"
}

Version pinning examples:

// Pin to specific patch version
{ "base_image": "langchain/langgraph-api:0.2.47" }

// Pin to minor version (gets latest patch)
{ "base_image": "langchain/langgraph-api:0.2" }

// Use latest
{ "base_image": "langchain/langgraph-api" }

`api_version`

Type: string
Required: No API server version to use. Alternative to specifying version in base_image.

{
  "api_version": "0.2.47"
}

`image_distro`

Type: "debian" | "wolfi" | "bookworm"
Default: "debian" Linux distribution for the base image.

{
  "image_distro": "wolfi"
}

"debian": Standard Debian-based image
"wolfi": Minimal, security-focused distribution
"bookworm": Debian 12 (Bookworm)

`dockerfile_lines`

Type: string[]
Required: No Custom Dockerfile instructions to append after the base image.

{
  "dockerfile_lines": [
    "RUN apt-get update && apt-get install -y libmagic-dev",
    "ENV MY_CUSTOM_VAR=production",
    "RUN pip install --no-cache-dir some-binary-package"
  ]
}

Common use cases:

{
  "dockerfile_lines": [
    // Install system dependencies
    "RUN apt-get update && apt-get install -y ffmpeg",
    
    // Set environment variables
    "ENV TOKENIZERS_PARALLELISM=false",
    
    // Create directories
    "RUN mkdir -p /app/data",
    
    // Install binary packages
    "RUN pip install --no-cache-dir torch==2.0.0"
  ]
}

Store Configuration

`store`

Type: StoreConfig
Required: No Configuration for the built-in long-term memory store with semantic search.

{
  "store": {
    "index": {
      "embed": "openai:text-embedding-3-large",
      "dims": 3072,
      "fields": ["title", "content"]
    },
    "ttl": {
      "refresh_on_read": true,
      "default_ttl": 1440,
      "sweep_interval_minutes": 60
    }
  }
}

`store.index`

Semantic search configuration. Required fields:

embed: Embedding model identifier
dims: Embedding dimension

Optional fields:

fields: JSON fields to embed (default: ["$"] - entire object)

Embedding model formats:

// Provider:model format
{ "embed": "openai:text-embedding-3-large" }

// Local function
{ "embed": "./src/embeddings.py:embed_function" }

Common embedding dimensions:

Model	Dimensions
`openai:text-embedding-3-large`	3072
`openai:text-embedding-3-small`	1536
`openai:text-embedding-ada-002`	1536
`cohere:embed-english-v3.0`	1024
`cohere:embed-multilingual-v3.0`	1024

`store.ttl`

Time-to-live configuration for automatic data expiration.

{
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "default_ttl": 1440,
      "sweep_interval_minutes": 60
    }
  }
}

refresh_on_read: Refresh TTL on read operations (default: true)
default_ttl: Default TTL in minutes for new items
sweep_interval_minutes: Interval between TTL sweep iterations

Checkpointer Configuration

`checkpointer`

Type: CheckpointerConfig
Required: No Configuration for custom checkpointer implementations.

{
  "checkpointer": {
    "path": "./src/checkpointer.py:create_checkpointer",
    "ttl": {
      "strategy": "keep_latest",
      "default_ttl": 10080,
      "sweep_interval_minutes": 60
    },
    "serde": {
      "allowed_msgpack_modules": [
        ["my_agent.models", "MyState"]
      ],
      "pickle_fallback": false
    }
  }
}

`checkpointer.path`

Import path to an async context manager that yields a BaseCheckpointSaver instance.

from contextlib import asynccontextmanager
from langgraph.checkpoint import BaseCheckpointSaver

@asynccontextmanager
async def create_checkpointer():
    # Initialize checkpointer
    checkpointer = MyCheckpointer(...)
    try:
        yield checkpointer
    finally:
        # Cleanup
        await checkpointer.close()

`checkpointer.ttl`

Thread TTL configuration:

{
  "ttl": {
    "strategy": "delete",
    "default_ttl": 10080,
    "sweep_interval_minutes": 60,
    "sweep_limit": 1000
  }
}

strategy: "delete" (remove thread) or "keep_latest" (keep latest state)
default_ttl: Default TTL in minutes
sweep_interval_minutes: Interval between sweeps (default: ~5 minutes)
sweep_limit: Max threads per sweep (default: 1000)

`checkpointer.serde`

Serialization/deserialization configuration:

{
  "serde": {
    "allowed_json_modules": [
      ["my_agent", "my_file", "SomeType"]
    ],
    "allowed_msgpack_modules": [
      ["my_agent.models", "MyState"]
    ],
    "pickle_fallback": true
  }
}

Authentication Configuration

`auth`

Type: AuthConfig
Required: No Custom authentication configuration.

{
  "auth": {
    "path": "./src/auth.py:my_auth",
    "disable_studio_auth": false,
    "openapi": {
      "securitySchemes": {
        "OAuth2": {
          "type": "oauth2",
          "flows": {
            "password": {
              "tokenUrl": "/token",
              "scopes": {
                "read": "Read access",
                "write": "Write access"
              }
            }
          }
        }
      },
      "security": [
        {"OAuth2": ["read", "write"]}
      ]
    },
    "cache": {
      "cache_keys": ["user_id"],
      "ttl_seconds": 3600,
      "max_size": 1000
    }
  }
}

Encryption Configuration

`encryption`

Type: EncryptionConfig
Required: No Custom at-rest encryption for sensitive data.

{
  "encryption": {
    "path": "./src/encryption.py:my_encryption"
  }
}

HTTP Server Configuration

`http`

Type: HttpConfig
Required: No Configuration for the built-in HTTP server.

{
  "http": {
    "app": "./src/app.py:custom_app",
    "mount_prefix": "/api",
    "disable_assistants": false,
    "disable_threads": false,
    "disable_runs": false,
    "disable_store": false,
    "disable_mcp": false,
    "disable_a2a": false,
    "disable_meta": false,
    "disable_ui": false,
    "disable_webhooks": false,
    "cors": {
      "allow_origins": ["https://example.com"],
      "allow_methods": ["GET", "POST"],
      "allow_headers": ["Content-Type", "Authorization"],
      "allow_credentials": true,
      "max_age": 600
    },
    "configurable_headers": {
      "includes": ["x-custom-*"],
      "excludes": ["*key*", "*token*"]
    },
    "middleware_order": "middleware_first",
    "enable_custom_route_auth": false
  }
}

Endpoint Control

Disable specific endpoint groups:

{
  "http": {
    "disable_assistants": true,  // Removes /assistants routes
    "disable_threads": true,     // Removes /threads routes
    "disable_runs": true,        // Removes /runs routes
    "disable_store": true,       // Removes /store routes
    "disable_mcp": true,         // Removes /mcp routes
    "disable_a2a": true,         // Removes /a2a routes
    "disable_meta": true,        // Removes /openapi.json, /info, /metrics, /docs
    "disable_ui": true,          // Removes /ui routes
    "disable_webhooks": true     // Disables webhook delivery
  }
}

CORS Configuration

{
  "http": {
    "cors": {
      "allow_origins": ["https://app.example.com"],
      "allow_methods": ["GET", "POST", "PUT", "DELETE"],
      "allow_headers": ["Content-Type", "Authorization"],
      "allow_credentials": true,
      "allow_origin_regex": "^https://.*\\.example\\.com$",
      "expose_headers": ["X-Request-ID"],
      "max_age": 3600
    }
  }
}

Webhooks Configuration

`webhooks`

Type: WebhooksConfig
Required: No Configuration for outbound webhook delivery.

{
  "webhooks": {
    "env_prefix": "LG_WEBHOOK_",
    "url": {
      "require_https": true,
      "allowed_domains": ["hooks.example.com", "*.mycorp.com"],
      "allowed_ports": [443, 8443],
      "max_url_length": 2048,
      "disable_loopback": true
    },
    "headers": {
      "Authorization": "Bearer ${{ env.LG_WEBHOOK_TOKEN }}",
      "X-Custom-Header": "static-value"
    }
  }
}

UI Configuration

`ui`

Type: Record<string, string>
Required: No Named UI components emitted by your agent.

{
  "ui": {
    "chat": "./src/ui/chat.tsx",
    "dashboard": "./src/ui/dashboard.tsx"
  }
}

`ui_config`

Type: object
Required: No Additional UI configuration.

{
  "ui_config": {
    "theme": "dark",
    "title": "My Agent"
  }
}

Complete Example

Here’s a comprehensive configuration example:

{
  "$schema": "https://langgra.ph/schema.json",
  "python_version": "3.12",
  "api_version": "0.2.47",
  "image_distro": "debian",
  "pip_installer": "uv",
  
  "dependencies": [
    "langchain-openai>=0.1.0",
    "langchain-anthropic>=0.1.0",
    "langchain-community",
    "wikipedia",
    "."
  ],
  
  "graphs": {
    "agent": {
      "path": "./src/agent.py:graph",
      "description": "Main ReAct agent with web search"
    },
    "research": {
      "path": "./src/research.py:research_graph",
      "description": "Multi-agent research assistant"
    }
  },
  
  "env": ".env",
  
  "store": {
    "index": {
      "embed": "openai:text-embedding-3-large",
      "dims": 3072,
      "fields": ["title", "content"]
    },
    "ttl": {
      "default_ttl": 10080,
      "sweep_interval_minutes": 60
    }
  },
  
  "checkpointer": {
    "ttl": {
      "strategy": "keep_latest",
      "default_ttl": 10080
    }
  },
  
  "http": {
    "cors": {
      "allow_origins": ["https://app.example.com"],
      "allow_credentials": true
    }
  },
  
  "dockerfile_lines": [
    "RUN apt-get update && apt-get install -y ffmpeg"
  ]
}

Validation

The CLI validates your configuration when running any command. Common errors:

Missing Required Fields

Error: No graphs found in config. Add at least one graph to 'graphs' dictionary.

Fix: Add at least one graph definition.

Invalid Python Version

Error: Python version 3.10 is not supported. Minimum required version is 3.11.

Fix: Use Python 3.11 or higher.

Invalid Graph Path

Error: Import string "./agent.py" must be in format "<module>:<attribute>".

Fix: Use correct format: "./agent.py:graph"

Reserved Package Names

Error: Package name 'langgraph' used in local dep '.' is reserved. Rename the directory.

Fix: Don’t use reserved names for your package directories.

Next Steps

Learn about CLI commands
Explore deployment guide
Read about building graphs

​Configuration Reference

​Schema

​Configuration Structure

​Minimal Configuration

​Complete Example

​Core Fields

​dependencies

​graphs

​env

​Python Configuration

​python_version

​pip_config_file

​pip_installer

​keep_pkg_tools

​Node.js Configuration

​node_version

​Docker Configuration

​base_image

​api_version

​image_distro

​dockerfile_lines

​Store Configuration

​store

​store.index

​store.ttl

​Checkpointer Configuration

​checkpointer

​checkpointer.path

​checkpointer.ttl

​checkpointer.serde

​Authentication Configuration

​auth

​Encryption Configuration

​encryption

​HTTP Server Configuration

​http

​Endpoint Control

​CORS Configuration

​Webhooks Configuration

​webhooks

​UI Configuration

​ui

​ui_config

​Complete Example

​Validation

​Missing Required Fields

​Invalid Python Version

​Invalid Graph Path

​Reserved Package Names

​Next Steps

Configuration Reference

Schema

Configuration Structure

Minimal Configuration

Complete Example

Core Fields

`dependencies`

`graphs`

`env`

Python Configuration

`python_version`

`pip_config_file`

`pip_installer`

`keep_pkg_tools`

Node.js Configuration

`node_version`

Docker Configuration

`base_image`

`api_version`

`image_distro`

`dockerfile_lines`

Store Configuration

`store`

`store.index`

`store.ttl`

Checkpointer Configuration

`checkpointer`

`checkpointer.path`

`checkpointer.ttl`

`checkpointer.serde`

Authentication Configuration

`auth`

Encryption Configuration

`encryption`

HTTP Server Configuration

`http`

Endpoint Control

CORS Configuration

Webhooks Configuration

`webhooks`

UI Configuration

`ui`

`ui_config`

Complete Example

Validation

Missing Required Fields

Invalid Python Version

Invalid Graph Path

Reserved Package Names

Next Steps