The LangGraph command line interface includes commands to build and run a LangGraph Platform API server locally in Docker. For development and testing, you can use the CLI to deploy a local API server.

​
Installation

  1. Ensure that Docker is installed (e.g. docker --version).
  2. Install the CLI package:
pip install langgraph-cli
  1. Run the command langgraph --help or npx @langchain/langgraph-cli --help to confirm that the CLI is working correctly.

​
Configuration File

The LangGraph CLI requires a JSON configuration file that follows this schema. It contains the following properties:
The LangGraph CLI defaults to using the configuration file langgraph.json in the current directory.
KeyDescription
dependenciesRequired. Array of dependencies for LangGraph Platform API server. Dependencies can be one of the following:
  • A single period ("."), which will look for local Python packages.
  • The directory path where pyproject.toml, setup.py or requirements.txt is located.
    For example, if requirements.txt is located in the root of the project directory, specify "./". If it’s located in a subdirectory called local_package, specify "./local_package". Do not specify the string "requirements.txt" itself.
  • A Python package name.
graphsRequired. Mapping from graph ID to path where the compiled graph or a function that makes a graph is defined. Example:
  • ./your_package/your_file.py:variable, where variable is an instance of langgraph.graph.state.CompiledStateGraph
  • ./your_package/your_file.py:make_graph, where make_graph is a function that takes a config dictionary (langchain_core.runnables.RunnableConfig) and returns an instance of langgraph.graph.state.StateGraph or langgraph.graph.state.CompiledStateGraph. See how to rebuild a graph at runtime for more details.
auth(Added in v0.0.11) Auth configuration containing the path to your authentication handler. Example: ./your_package/auth.py:auth, where auth is an instance of langgraph_sdk.Auth. See authentication guide for details.
base_imageOptional. Base image to use for the LangGraph API server. Defaults to langchain/langgraph-api or langchain/langgraphjs-api. Use this to pin your builds to a particular version of the langgraph API, such as "langchain/langgraph-server:0.2". See https://hub.docker.com/r/langchain/langgraph-server/tags for more details. (added in langgraph-cli==0.2.8)
image_distroOptional. Linux distribution for the base image. Must be either "debian" or "wolfi". If omitted, defaults to "debian". Available in langgraph-cli>=0.2.11.
envPath to .env file or a mapping from environment variable to its value.
storeConfiguration for adding semantic search and/or time-to-live (TTL) to the BaseStore. Contains the following fields:
  • index (optional): Configuration for semantic search indexing with fields embed, dims, and optional fields.
  • ttl (optional): Configuration for item expiration. An object with optional fields: refresh_on_read (boolean, defaults to true), default_ttl (float, lifespan in minutes, defaults to no expiration), and sweep_interval_minutes (integer, how often to check for expired items, defaults to no sweeping).
uiOptional. Named definitions of UI components emitted by the agent, each pointing to a JS/TS file. (added in langgraph-cli==0.1.84)
python_version3.11, 3.12, or 3.13. Defaults to 3.11.
node_versionSpecify node_version: 20 to use LangGraph.js.
pip_config_filePath to pip config file.
pip_installer(Added in v0.3) Optional. Python package installer selector. It can be set to "auto", "pip", or "uv". From version 0.3 onward the default strategy is to run uv pip, which typically delivers faster builds while remaining a drop-in replacement. In the uncommon situation where uv cannot handle your dependency graph or the structure of your pyproject.toml, specify "pip" here to revert to the earlier behaviour.
keep_pkg_tools(Added in v0.3.4) Optional. Control whether to retain Python packaging tools (pip, setuptools, wheel) in the final image. Accepted values:
  • true : Keep all three tools (skip uninstall).
  • false / omitted : Uninstall all three tools (default behaviour).
  • list[str] : Names of tools to retain. Each value must be one of “pip”, “setuptools”, “wheel”.
. By default, all three tools are uninstalled.
dockerfile_linesArray of additional lines to add to Dockerfile following the import from parent image.
checkpointerConfiguration for the checkpointer. Contains a ttl field which is an object with the following keys:
  • strategy: How to handle expired checkpoints (e.g., "delete").
  • sweep_interval_minutes: How often to check for expired checkpoints (integer).
  • default_ttl: Default time-to-live for checkpoints in minutes (integer). Defines how long checkpoints are kept before the specified strategy is applied.
httpHTTP server configuration with the following fields:
  • app: Path to custom Starlette/FastAPI app (e.g., "./src/agent/webapp.py:app"). See custom routes guide.
  • cors: CORS configuration with fields for allow_origins, allow_methods, allow_headers, etc.
  • configurable-headers: Define which request headers to exclude or include as a run’s configurable values.
  • disable_assistants: Disable /assistants routes
  • disable_mcp: Disable /mcp routes
  • disable_meta: Disable /ok, /info, /metrics, and /docs routes
  • disable_runs: Disable /runs routes
  • disable_store: Disable /store routes
  • disable_threads: Disable /threads routes
  • disable_ui: Disable /ui routes
  • disable_webhooks: Disable webhooks calls on run completion in all routes
  • mount_prefix: Prefix for mounted routes (e.g., “/my-deployment/api”)

​
Examples

​
Basic Configuration

{
  "dependencies": ["."],
  "graphs": {
    "chat": "./chat/graph.py:graph"
  }
}

​
Using Wolfi Base Images

You can specify the Linux distribution for your base image using the image_distro field. Valid options are debian or wolfi. Wolfi is the recommended option as it provides smaller and more secure images. This is available in langgraph-cli>=0.2.11.
{
  "dependencies": ["."],
  "graphs": {
    "chat": "./chat/graph.py:graph"
  },
  "image_distro": "wolfi"
}

​
Adding semantic search to the store

All deployments come with a DB-backed BaseStore. Adding an “index” configuration to your langgraph.json will enable semantic search within the BaseStore of your deployment.The index.fields configuration determines which parts of your documents to embed:
  • If omitted or set to ["$"], the entire document will be embedded
  • To embed specific fields, use JSON path notation: ["metadata.title", "content.text"]
  • Documents missing specified fields will still be stored but won’t have embeddings for those fields
  • You can still override which fields to embed on a specific item at put time using the index parameter
{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "index": {
      "embed": "openai:text-embedding-3-small",
      "dims": 1536,
      "fields": ["$"]
    }
  }
}
Common 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-english-light-v3.0: 384
  • cohere:embed-multilingual-v3.0: 1024
  • cohere:embed-multilingual-light-v3.0: 384

​
Semantic search with a custom embedding function

If you want to use semantic search with a custom embedding function, you can pass a path to a custom embedding function:
{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "index": {
      "embed": "./embeddings.py:embed_texts",
      "dims": 768,
      "fields": ["text", "summary"]
    }
  }
}
The embed field in store configuration can reference a custom function that takes a list of strings and returns a list of embeddings. Example implementation:
# embeddings.py
def embed_texts(texts: list[str]) -> list[list[float]]:
    """Custom embedding function for semantic search."""
    # Implementation using your preferred embedding model
    return [[0.1, 0.2, ...] for _ in texts]  # dims-dimensional vectors

​
Adding custom authentication

{
  "dependencies": ["."],
  "graphs": {
    "chat": "./chat/graph.py:graph"
  },
  "auth": {
    "path": "./auth.py:auth",
    "openapi": {
      "securitySchemes": {
        "apiKeyAuth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      },
      "security": [{ "apiKeyAuth": [] }]
    },
    "disable_studio_auth": false
  }
}
See the authentication conceptual guide for details, and the setting up custom authentication guide for a practical walk through of the process.

​
Configuring Store Item Time-to-Live

You can configure default data expiration for items/memories in the BaseStore using the store.ttl key. This determines how long items are retained after they are last accessed (with reads potentially refreshing the timer based on refresh_on_read). Note that these defaults can be overwritten on a per-call basis by modifying the corresponding arguments in get, search, etc.The ttl configuration is an object containing optional fields:
  • refresh_on_read: If true (the default), accessing an item via get or search resets its expiration timer. Set to false to only refresh TTL on writes (put).
  • default_ttl: The default lifespan of an item in minutes. If not set, items do not expire by default.
  • sweep_interval_minutes: How frequently (in minutes) the system should run a background process to delete expired items. If not set, sweeping does not occur automatically.
Here is an example enabling a 7-day TTL (10080 minutes), refreshing on reads, and sweeping every hour:
{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "sweep_interval_minutes": 60,
      "default_ttl": 10080 
    }
  }
}

​
Configuring Checkpoint Time-to-Live

You can configure the time-to-live (TTL) for checkpoints using the checkpointer key. This determines how long checkpoint data is retained before being automatically handled according to the specified strategy (e.g., deletion). The ttl configuration is an object containing:
  • strategy: The action to take on expired checkpoints (currently "delete" is the only accepted option).
  • sweep_interval_minutes: How frequently (in minutes) the system checks for expired checkpoints.
  • default_ttl: The default lifespan of a checkpoint in minutes.
Here’s an example setting a default TTL of 30 days (43200 minutes):
{
  "dependencies": ["."],
  "graphs": {
    "chat": "./chat/graph.py:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 10,
      "default_ttl": 43200
    }
  }
}
In this example, checkpoints older than 30 days will be deleted, and the check runs every 10 minutes.

​
Commands

Usage
The base command for the LangGraph CLI is langgraph.
langgraph [OPTIONS] COMMAND [ARGS]

​
dev

Run LangGraph API server in development mode with hot reloading and debugging capabilities. This lightweight server requires no Docker installation and is suitable for development and testing. State is persisted to a local directory.
Currently, the CLI only supports Python >= 3.11.
InstallationThis command requires the “inmem” extra to be installed:
pip install -U "langgraph-cli[inmem]"
Usage
langgraph dev [OPTIONS]
Options
OptionDefaultDescription
-c, --config FILElanggraph.jsonPath to configuration file declaring dependencies, graphs and environment variables
--host TEXT127.0.0.1Host to bind the server to
--port INTEGER2024Port to bind the server to
--no-reloadDisable auto-reload
--n-jobs-per-worker INTEGERNumber of jobs per worker. Default is 10
--debug-port INTEGERPort for debugger to listen on
--wait-for-clientFalseWait for a debugger client to connect to the debug port before starting the server
--no-browserSkip automatically opening the browser when the server starts
--studio-url TEXTURL of the LangGraph Studio instance to connect to. Defaults to https://smith.langchain.com
--allow-blockingFalseDo not raise errors for synchronous I/O blocking operations in your code (added in 0.2.6)
--tunnelFalseExpose the local server via a public tunnel (Cloudflare) for remote frontend access. This avoids issues with browsers like Safari or networks blocking localhost connections
--helpDisplay command documentation

​
build

Build LangGraph Platform API server Docker image.Usage
langgraph build [OPTIONS]
Options
OptionDefaultDescription
--platform TEXTTarget platform(s) to build the Docker image for. Example: langgraph build --platform linux/amd64,linux/arm64
-t, --tag TEXTRequired. Tag for the Docker image. Example: langgraph build -t my-image
--pull / --no-pull--pullBuild with latest remote Docker image. Use --no-pull for running the LangGraph Platform API server with locally built images.
-c, --config FILElanggraph.jsonPath to configuration file declaring dependencies, graphs and environment variables.
--helpDisplay command documentation.

​
up

Start LangGraph API server. For local testing, requires a LangSmith API key with access to LangGraph Platform. Requires a license key for production use.Usage
langgraph up [OPTIONS]
Options
OptionDefaultDescription
--waitWait for services to start before returning. Implies —detach
--base-image TEXTlangchain/langgraph-apiBase image to use for the LangGraph API server. Pin to specific versions using version tags.
--image TEXTDocker image to use for the langgraph-api service. If specified, skips building and uses this image directly.
--postgres-uri TEXTLocal databasePostgres URI to use for the database.
--watchRestart on file changes
--debugger-base-url TEXThttp://127.0.0.1:[PORT]URL used by the debugger to access LangGraph API.
--debugger-port INTEGERPull the debugger image locally and serve the UI on specified port
--verboseShow more output from the server logs.
-c, --config FILElanggraph.jsonPath to configuration file declaring dependencies, graphs and environment variables.
-d, --docker-compose FILEPath to docker-compose.yml file with additional services to launch.
-p, --port INTEGER8123Port to expose. Example: langgraph up --port 8000
--pull / --no-pullpullPull latest images. Use --no-pull for running the server with locally-built images. Example: langgraph up --no-pull
--recreate / --no-recreateno-recreateRecreate containers even if their configuration and image haven’t changed
--helpDisplay command documentation.

​
dockerfile

Generate a Dockerfile for building a LangGraph Platform API server Docker image.Usage
langgraph dockerfile [OPTIONS] SAVE_PATH
Options
OptionDefaultDescription
-c, --config FILElanggraph.jsonPath to the configuration file declaring dependencies, graphs and environment variables.
--helpShow this message and exit.
Example:
langgraph dockerfile -c langgraph.json Dockerfile
This generates a Dockerfile that looks similar to:
FROM langchain/langgraph-api:3.11

ADD ./pipconf.txt /pipconfig.txt

RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt langchain_community langchain_anthropic langchain_openai wikipedia scikit-learn

ADD ./graphs /deps/__outer_graphs/src
RUN set -ex && \
    for line in '[project]' \
                'name = "graphs"' \
                'version = "0.1"' \
                '[tool.setuptools.package-data]' \
                '"*" = ["**/*"]'; do \
        echo "$line" >> /deps/__outer_graphs/pyproject.toml; \
    done

RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*

ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_graphs/src/agent.py:graph", "storm": "/deps/__outer_graphs/src/storm.py:graph"}'
The langgraph dockerfile command translates all the configuration in your langgraph.json file into Dockerfile commands. When using this command, you will have to re-run it whenever you update your langgraph.json file. Otherwise, your changes will not be reflected when you build or run the dockerfile.