LangGraph CLI

LangGraph CLI is a command-line tool for building and running the Agent Server locally. The resulting server exposes all API endpoints for runs, threads, assistants, etc., and includes supporting services such as a managed database for checkpointing and storage.

Installation

1. Ensure Docker is installed (e.g., docker --version).

2. Install the CLI:

   [Python (pip)]

   pip install langgraph-cli
   

   # Use latest on demand
   npx @langchain/langgraph-cli
   
   # Or install globally (available as `langgraphjs`)
   npm install -g @langchain/langgraph-cli
   

3. Verify the install

   [Python (pip)]

   langgraph --help
   

   npx @langchain/langgraph-cli --help
   

Quick commands

Command	What it does
langgraph dev	Starts a lightweight local dev server (no Docker required), ideal for rapid testing.
langgraph build	Builds a Docker image of your LangGraph API server for deployment.
langgraph deploy	Builds and deploys a LangGraph image directly to LangSmith Deployments in a single step.
langgraph dockerfile	Emits a Dockerfile derived from your config for custom builds.
langgraph up	Starts the LangGraph API server locally in Docker. Requires Docker running; LangSmith API key for local dev; license for production.

For JS, use npx @langchain/langgraph-cli <command> (or langgraphjs if installed globally).

Configuration file

To build and run a valid application, 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 named langgraph.json in the current directory.

Python

Key	Description
dependencies	Required. Array of dependencies for LangSmith 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.
graphs	Required. 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_image	Optional. 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_distro	Optional. Linux distribution for the base image. Must be one of "debian", "wolfi", "bookworm", or "bullseye". If omitted, defaults to "debian". Available in langgraph-cli>=0.2.11.
env	Path to .env file or a mapping from environment variable to its value.
store	Configuration 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; applied to newly created items only; existing items are unchanged; defaults to no expiration), and sweep_interval_minutes (integer, how often to check for expired items, defaults to no sweeping).
ui	Optional. Named definitions of UI components emitted by the agent, each pointing to a JS/TS file. (added in langgraph-cli==0.1.84)
python_version	3.11, 3.12, or 3.13. Defaults to 3.11.
node_version	Specify node_version: 20 to use LangGraph.js.
pip_config_file	Path 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_lines	Array of additional lines to add to Dockerfile following the import from parent image.
checkpointer	Configuration for the checkpointer. Supports: backend (optional): "default", "mongo", or "custom". Defaults to "default" (PostgreSQL). See Configure checkpointer backend. path (optional): Path to a custom checkpointer factory (when backend is "custom"). See Custom checkpointer. ttl (optional): Object with strategy, sweep_interval_minutes, default_ttl, and sweep_limit (Agent server v0.8+) controlling checkpoint expiry. serde (optional, Agent server v0.5+): Object with allowed_json_modules and pickle_fallback to tune deserialization behavior.
http	HTTP 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 such as allow_origins, allow_methods, allow_headers, allow_credentials, allow_origin_regex, expose_headers, and max_age. configurable_headers: Define which request headers to expose as configurable values via includes / excludes patterns. logging_headers: Mirror of configurable_headers for excluding sensitive headers from logs. middleware_order: Choose how custom middleware and auth interact. auth_first runs authentication hooks before custom middleware, while middleware_first (default) runs your middleware first. enable_custom_route_auth: Apply auth checks to routes added through app. Route disable flags — selectively turn off groups of built-in endpoints: disable_meta: Disables the / (root), /info, /metrics, /docs, and /openapi.json system routes. The /ok health check remains available. disable_assistants: Disables all /assistants/* routes. disable_runs: Disables all /runs/* routes. disable_threads: Disables all /threads/* routes. disable_store: Disables all /store/* routes. disable_ui: Disables all /ui/* routes. disable_mcp: Disables the /mcp endpoint. See Disable MCP. disable_a2a: Disables the /a2a/* endpoint. See Disable A2A. disable_webhooks: Disables webhook delivery on run completion (not a route toggle). See Disable webhooks. mount_prefix: Prefix for mounted routes (e.g., “/my-deployment/api”).
webhooks	(Added in v0.5.36) Configuration for outbound webhook delivery. Contains: env_prefix: Required prefix for environment variables referenced in header templates (defaults to LG_WEBHOOK_). headers: Static headers to include with webhook requests. Values may contain templates like ${{ env.VAR }}. url: URL validation policy with allowed_domains, allowed_ports, require_https, disable_loopback, and max_url_length.
api_version	(Added in v0.3.7) Which semantic version of the LangGraph API server to use (e.g., "0.3"). Defaults to latest. Check the server changelog for details on each release.

JS

Key	Description
graphs	Required. Mapping from graph ID to path where the compiled graph or a function that makes a graph is defined. Example: ./src/graph.ts:variable, where variable is an instance of CompiledStateGraph ./src/graph.ts:makeGraph, where makeGraph is a function that takes a config dictionary (LangGraphRunnableConfig) and returns an instance of StateGraph or CompiledStateGraph. See how to rebuild a graph at runtime for more details.
env	Path to .env file or a mapping from environment variable to its value.
store	Configuration 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; applied to newly created items only; existing items are unchanged; defaults to no expiration), and sweep_interval_minutes (integer, how often to check for expired items, defaults to no sweeping).
node_version	Specify node_version: 20 to use LangGraph.js.
dockerfile_lines	Array of additional lines to add to Dockerfile following the import from parent image.
checkpointer	Configuration for the checkpointer. Supports: backend (optional): "default", "mongo", or "custom". Defaults to "default" (PostgreSQL). See Configure checkpointer backend. path (optional): Path to a custom checkpointer factory (when backend is "custom"). See Custom checkpointer. ttl (optional): Object with strategy, sweep_interval_minutes, default_ttl, and sweep_limit (Agent server v0.8+) controlling checkpoint expiry. serde (optional, Agent server v0.5+): Object with allowed_json_modules and pickle_fallback to tune deserialization behavior.
http	HTTP server configuration mirroring the Python options: cors with allow_origins, allow_methods, allow_headers, allow_credentials, allow_origin_regex, expose_headers, max_age. configurable_headers and logging_headers pattern lists. middleware_order (auth_first or middleware_first). enable_custom_route_auth plus the same boolean route toggles as above.
webhooks	(Added in v0.5.36) Configuration for outbound webhook delivery. Contains: env_prefix: Required prefix for environment variables referenced in header templates (defaults to LG_WEBHOOK_). headers: Static headers to include with webhook requests. Values may contain templates like ${{ env.VAR }}. url: URL validation policy with allowed_domains, allowed_ports, require_https, disable_loopback, and max_url_length.
api_version	(Added in v0.3.7) Which semantic version of the LangGraph API server to use (e.g., "0.3"). Defaults to latest. Check the server changelog for details on each release.

Examples

Python

Basic configuration

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

Using Wolfi base images

You can specify the Linux distribution for your base image using the image_distro field. Valid options are debian, wolfi, bookworm, or bullseye. Wolfi is the recommended option as it provides smaller and more secure images. This is available in langgraph-cli>=0.2.11.

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph: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

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph: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. Applies only to newly created items; existing items are not modified. 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:

{
  "$schema": "https://langgra.ph/schema.json",
  "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). Two optional sub-objects are supported:

• ttl: Includes strategy, sweep_interval_minutes, default_ttl, and sweep_limit (Agent server v0.8+), which collectively set how checkpoints expire.
• serde (Agent server v0.5+) : Lets you control deserialization behavior for checkpoint payloads.

Here’s an example setting a default TTL of 30 days (43200 minutes):

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph: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.

Configuring checkpointer serde

The checkpointer.serde object shapes deserialization:

• allowed_json_modules defines an allow list for custom Python objects you want the server to be able to deserialize from payloads saved in “json” mode. This is a list of [path, to, module, file, symbol] sequences. If omitted, only LangChain-safe defaults are allowed. You can unsafely set to true to allow any module to be deserialized.
• pickle_fallback: Whether to fall back to pickle deserialization when JSON decoding fails.

{
  "checkpointer": {
    "serde": {
      "allowed_json_modules": [
        ["my_agent", "auth", "SessionState"]
      ]
    }
  }
}

Customizing HTTP middleware and headers

The http block lets you fine-tune request handling:

• middleware_order: Choose "auth_first" to run authentication before your middleware, or "middleware_first" (default) to invert that order.

• enable_custom_route_auth: Extend authentication to routes you mount through http.app.

• configurable_headers / logging_headers: Each accepts an object with optional includes and excludes arrays; wildcards are supported and exclusions run before inclusions.

• cors: Customize your server’s CORS (Cross-Origin Resource Sharing) configuration. Example langgraph.json file for configuring CORS:

  {
    ...
    "http": {
      "cors": {
        "allow_origins": ["https://example.com", "https://app.example.com"],
        "allow_methods": ["GET", "POST"],
        "allow_headers": ["Authorization", "Content-Type"],
        "allow_credentials": true,
        "allow_origin_regex": "^https://.*\\.example\\.com$",
        "expose_headers": ["x-pagination-total", "x-pagination-next", "x-request-id"],
        "max_age": 600
      }
    },
    ...
  }
  
  Customizing your server’s CORS configuration will override the functionality of setting the CORS_ALLOW_ORIGINS environment variable.

Configuring webhooks

You can configure custom headers and URL restrictions for outbound webhook requests:

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "webhooks": {
    "headers": {
      "Authorization": "Bearer ${{ env.LG_WEBHOOK_TOKEN }}"
    },
    "url": {
      "allowed_domains": ["*.mycompany.com"],
      "require_https": true
    }
  }
}

See Use webhooks for details on header configuration, environment variable templating, and URL restrictions.

Pinning API version

(Added in v0.3.7)

You can pin the API version of the Agent Server by using the api_version key. This is useful if you want to ensure that your server uses a specific version of the API. By default, builds in Cloud deployments use the latest stable version of the server. This can be pinned by setting the api_version key to a specific version.

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

Disabling built-in routes

You can selectively disable groups of built-in HTTP routes using boolean flags in the http configuration block. This is useful for production deployments where you want to minimize the server’s exposed surface area.

For example, to disable the system information and documentation routes:

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "http": {
    "disable_meta": true
  }
}

Setting disable_meta to true disables the following routes:

• / — root health check
• /info — server version and configuration info
• /metrics — Prometheus and JSON metrics
• /docs — API documentation UI
• /openapi.json — OpenAPI specification

The /ok health check endpoint remains available even when disable_meta is set, so orchestrators like Kubernetes can still perform liveness and readiness probes.

Other route disable flags include disable_assistants, disable_runs, disable_threads, disable_store, and disable_ui. For MCP, A2A, and webhooks, see their respective guides: Disable MCP, Disable A2A, Disable webhooks.

JS

Basic configuration

{
  "$schema": "https://langgra.ph/schema.json",
  "graphs": {
    "chat": "./src/graph.ts:graph"
  }
}

Pinning API version

(Added in v0.3.7)

You can pin the API version of the Agent Server by using the api_version key. This is useful if you want to ensure that your server uses a specific version of the API. By default, builds in Cloud deployments use the latest stable version of the server. This can be pinned by setting the api_version key to a specific version.

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "./src/chat/graph.ts:graph"
  },
  "api_version": "0.2"
}

Disabling built-in routes

You can selectively disable groups of built-in HTTP routes using boolean flags in the http configuration block. This is useful for production deployments where you want to minimize the server’s exposed surface area.

For example, to disable the system information and documentation routes:

{
  "$schema": "https://langgra.ph/schema.json",
  "graphs": {
    "chat": "./src/chat/graph.ts:graph"
  },
  "http": {
    "disable_meta": true
  }
}

Setting disable_meta to true disables the following routes:

• / — root health check
• /info — server version and configuration info
• /metrics — Prometheus and JSON metrics
• /docs — API documentation UI
• /openapi.json — OpenAPI specification

The /ok health check endpoint remains available even when disable_meta is set, so orchestrators like Kubernetes can still perform liveness and readiness probes.

Other route disable flags include disable_assistants, disable_runs, disable_threads, disable_store, and disable_ui. For MCP, A2A, and webhooks, see their respective guides: Disable MCP, Disable A2A, Disable webhooks.

Commands

Usage

Python

The base command for the LangGraph CLI is langgraph.

langgraph [OPTIONS] COMMAND [ARGS]

JS

The base command for the LangGraph.js CLI is langgraphjs.

npx @langchain/langgraph-cli [OPTIONS] COMMAND [ARGS]

We recommend using npx to always use the latest version of the CLI.

dev

Python

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.

If you need more information on when to use langgraph dev vs langgraph up, refer to the Local development & testing guide for a detailed comparison.

Installation

This command requires the “inmem” extra to be installed:

pip install -U "langgraph-cli[inmem]"

Usage

langgraph dev [OPTIONS]

Options

Option	Default	Description
-c, --config FILE	langgraph.json	Path to configuration file declaring dependencies, graphs and environment variables
--host TEXT	127.0.0.1	Host to bind the server to
--port INTEGER	2024	Port to bind the server to
--no-reload		Disable auto-reload
--n-jobs-per-worker INTEGER		Number of jobs per worker. Default is 10
--debug-port INTEGER		Port for debugger to listen on
--wait-for-client	False	Wait for a debugger client to connect to the debug port before starting the server
--no-browser		Skip automatically opening the browser when the server starts
--studio-url TEXT		URL of the Studio instance to connect to. Defaults to https://smith.langchain.com
--allow-blocking	False	Do not raise errors for synchronous I/O blocking operations in your code (added in 0.2.6)
--tunnel	False	Expose the local server via a public tunnel (Cloudflare) for remote frontend access. This avoids issues with browsers like Safari or networks blocking localhost connections
--help		Display command documentation

JS

Run LangGraph API server in development mode with hot reloading capabilities. This lightweight server requires no Docker installation and is suitable for development and testing. State is persisted to a local directory.

Usage

npx @langchain/langgraph-cli dev [OPTIONS]

Options

Option	Default	Description
-c, --config FILE	langgraph.json	Path to configuration file declaring dependencies, graphs and environment variables
--host TEXT	127.0.0.1	Host to bind the server to
--port INTEGER	2024	Port to bind the server to
--no-reload		Disable auto-reload
--n-jobs-per-worker INTEGER		Number of jobs per worker. Default is 10
--debug-port INTEGER		Port for debugger to listen on
--wait-for-client	False	Wait for a debugger client to connect to the debug port before starting the server
--no-browser		Skip automatically opening the browser when the server starts
--studio-url TEXT		URL of the Studio instance to connect to. Defaults to https://smith.langchain.com
--allow-blocking	False	Do not raise errors for synchronous I/O blocking operations in your code
--tunnel	False	Expose the local server via a public tunnel (Cloudflare) for remote frontend access. This avoids issues with browsers or networks blocking localhost connections
--help		Display command documentation

build

Python

Build LangSmith API server Docker image.

Usage

langgraph build [OPTIONS]

Options

Option	Default	Description
--platform TEXT		Target platform(s) to build the Docker image for. Example: langgraph build --platform linux/amd64,linux/arm64
-t, --tag TEXT		Required. Tag for the Docker image. Example: langgraph build -t my-image
--pull / --no-pull	--pull	Build with latest remote Docker image. Use --no-pull for running the LangSmith API server with locally built images.
-c, --config FILE	langgraph.json	Path to configuration file declaring dependencies, graphs and environment variables.
--build-command TEXT*		Build command to run. Runs from the directory where your langgraph.json file lives. Example: langgraph build --build-command "yarn run turbo build"
--install-command TEXT*		Install command to run. Runs from the directory where you call langgraph build from. Example: langgraph build --install-command "yarn install"
--help		Display command documentation.

^*Only supported for JS deployments, will have no impact on Python deployments.

JS

Build LangSmith API server Docker image.

Usage

npx @langchain/langgraph-cli build [OPTIONS]

Options

Option	Default	Description
--platform TEXT		Target platform(s) to build the Docker image for. Example: langgraph build --platform linux/amd64,linux/arm64
-t, --tag TEXT		Required. Tag for the Docker image. Example: langgraph build -t my-image
--no-pull		Use locally built images. Defaults to false to build with latest remote Docker image.
-c, --config FILE	langgraph.json	Path to configuration file declaring dependencies, graphs and environment variables.
--help		Display command documentation.

deploy

Python

This command is in beta and under active development. Expect frequent updates and improvements.

Build and deploy a LangGraph image directly to LangSmith Deployments. This command builds a Docker image locally, pushes it to a managed registry, and creates or updates a deployment—all in a single step. If Docker is not installed, it triggers a remote build.

Prerequisites

• A LangSmith API key with access to Deployments.
• (Optional) Docker must be installed and the Docker daemon must be running for local builds. Not required for remote builds. Install Docker Desktop.

Works only with LangSmith Cloud.

Usage

langgraph deploy [OPTIONS] [DOCKER_BUILD_ARGS]

This command also accepts all langgraph build flags (--platform, -t, --pull, --no-pull, -c). For details, refer to langgraph build --help.

Options

Option	Default	Description
--api-key TEXT		API key for LangSmith Deployments. Can also be set via LANGGRAPH_HOST_API_KEY, LANGSMITH_API_KEY, or LANGCHAIN_API_KEY environment variable or .env file.
--name TEXT	Current directory name	Deployment name. Can also be set via LANGSMITH_DEPLOYMENT_NAME environment variable or .env file.
--deployment-id TEXT		ID of an existing deployment to update. If omitted, --name is used to find or create the deployment.
--deployment-type TEXT	dev	Deployment type (dev or prod). Used when creating a new deployment.
--remote / --no-remote		Force remote or local build. By default, builds remotely if Docker is not available locally.
--no-wait	False	Skip waiting for deployment status after pushing.
--verbose	False	Show detailed output including Docker build and push logs.
--help		Display command documentation.

Example

# Deploy with API key from .env file
langgraph deploy

# Deploy with inline API key
LANGSMITH_API_KEY=lsv2_... langgraph deploy

# Update an existing deployment
langgraph deploy --deployment-id abc123

# Deploy with inline deployment name
LANGSMITH_DEPLOYMENT_NAME=my-agent langgraph deploy

# Deploy to EU region
LANGGRAPH_HOST_URL=https://eu.api.host.langchain.com langgraph deploy

Deployments created through other methods (e.g., the LangSmith UI or GitHub integration) can also be updated with the langgraph deploy command.

deploy list

List LangSmith Deployments.

Usage

langgraph deploy list [OPTIONS]

Options

Option	Default	Description
--name-contains TEXT		Only show deployments whose names contain this value.
--api-key TEXT		API key. Can also be set via LANGGRAPH_HOST_API_KEY, LANGSMITH_API_KEY, or LANGCHAIN_API_KEY environment variable or .env file.
--help		Show this message and exit.

deploy revisions

[Beta] Manage deployment revisions.

Usage

langgraph deploy revisions [OPTIONS] COMMAND [ARGS]...

Options

Option	Default	Description
--help		Show this message and exit.

Commands

Command	Description
list	[Beta] List revisions for a LangSmith Deployment.

deploy revisions list

[Beta] List revisions for a LangSmith Deployment.

Use deploy list to list deployment IDs.

Usage

langgraph deploy revisions list [OPTIONS] DEPLOYMENT_ID

Options

Option	Default	Description
--limit INTEGER	10	Maximum number of revisions to return.
--api-key TEXT		API key. Can also be set via LANGGRAPH_HOST_API_KEY, LANGSMITH_API_KEY, or LANGCHAIN_API_KEY environment variable or .env file.
--help		Show this message and exit.

deploy delete

Delete a LangSmith Deployment.

Use deploy list to find the deployment ID to delete.

Usage

langgraph deploy delete [OPTIONS] DEPLOYMENT_ID

Options

Option	Default	Description
--force		Delete without prompting for confirmation.
--api-key TEXT		API key. Can also be set via LANGGRAPH_HOST_API_KEY, LANGSMITH_API_KEY, or LANGCHAIN_API_KEY environment variable or .env file.
--help		Show this message and exit.

deploy logs

Fetch LangSmith Deployment logs. Use deploy for agent runtime logs, or build for remote build logs.

Usage

langgraph deploy logs [OPTIONS]

Options

Option	Default	Description
-f, --follow	False	Continuously poll for new logs.
--end-time TEXT		ISO8601 end time. Example: 2026-03-08T00:00:00Z.
--start-time TEXT		ISO8601 start time. Example: 2026-03-08T00:00:00Z.
-q, --query TEXT		Search string filter.
--limit INTEGER	100	Max log entries to fetch.
--level [DEBUG|INFO|WARNING|ERROR|CRITICAL]		Filter by log level.
--revision-id TEXT		Specific revision ID. For build logs, defaults to the latest revision.
--type [deploy|build]	deploy	Log stream to fetch. deploy shows agent server runtime logs. build shows remote build logs.
--deployment-id TEXT		Deployment ID. If omitted, --name is used to find the deployment.
--name TEXT	Current directory name	Deployment name. Can also be set via LANGSMITH_DEPLOYMENT_NAME environment variable or .env file. Used when --deployment-id is not provided.
--api-key TEXT		API key. Can also be set via LANGGRAPH_HOST_API_KEY, LANGSMITH_API_KEY, or LANGCHAIN_API_KEY environment variable or .env file.
--help		Show this message and exit.

up

Python

Start LangGraph API server. For local testing, requires a LangSmith API key with access to LangSmith. Requires a license key for production use.

If you need more information on when to use langgraph dev vs langgraph up, refer to the Local development & testing guide for a detailed comparison.

Usage

langgraph up [OPTIONS]

Options

Option	Default	Description
--wait		Wait for services to start before returning. Implies —detach
--base-image TEXT	langchain/langgraph-api	Base image to use for the LangGraph API server. Pin to specific versions using version tags.
--image TEXT		Docker image to use for the langgraph-api service. If specified, skips building and uses this image directly.
--postgres-uri TEXT	Local database	Postgres URI to use for the database.
--watch		Restart on file changes
--debugger-base-url TEXT	http://127.0.0.1:[PORT]	URL used by the debugger to access LangGraph API.
--debugger-port INTEGER		Pull the debugger image locally and serve the UI on specified port
--verbose		Show more output from the server logs.
-c, --config FILE	langgraph.json	Path to configuration file declaring dependencies, graphs and environment variables.
-d, --docker-compose FILE		Path to docker-compose.yml file with additional services to launch.
-p, --port INTEGER	8123	Port to expose. Example: langgraph up --port 8000
--pull / --no-pull	pull	Pull latest images. Use --no-pull for running the server with locally-built images. Example: langgraph up --no-pull
--recreate / --no-recreate	no-recreate	Recreate containers even if their configuration and image haven’t changed
--help		Display command documentation.

JS

Start LangGraph API server. For local testing, requires a LangSmith API key with access to LangSmith. Requires a license key for production use.

Usage

npx @langchain/langgraph-cli up [OPTIONS]

Options

Option	Default	Description
--wait		Wait for services to start before returning. Implies —detach
--base-image TEXT	langchain/langgraph-api	Base image to use for the LangGraph API server. Pin to specific versions using version tags.
--image TEXT		Docker image to use for the langgraph-api service. If specified, skips building and uses this image directly.
--postgres-uri TEXT	Local database	Postgres URI to use for the database.
--watch		Restart on file changes
-c, --config FILE	langgraph.json	Path to configuration file declaring dependencies, graphs and environment variables.
-d, --docker-compose FILE		Path to docker-compose.yml file with additional services to launch.
-p, --port INTEGER	8123	Port to expose. Example: langgraph up --port 8000
--no-pull		Use locally built images. Defaults to false to build with latest remote Docker image.
--recreate		Recreate containers even if their configuration and image haven’t changed
--help		Display command documentation.

dockerfile

Python

Generate a Dockerfile for building a LangSmith API server Docker image.

Usage

langgraph dockerfile [OPTIONS] SAVE_PATH

Options

Option	Default	Description
-c, --config FILE	langgraph.json	Path to the configuration file declaring dependencies, graphs and environment variables.
--help		Show 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_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.

JS

Generate a Dockerfile for building a LangSmith API server Docker image.

Usage

npx @langchain/langgraph-cli dockerfile [OPTIONS] SAVE_PATH

Options

Option	Default	Description
-c, --config FILE	langgraph.json	Path to the configuration file declaring dependencies, graphs and environment variables.
--help		Show this message and exit.

Example:

npx @langchain/langgraph-cli dockerfile -c langgraph.json Dockerfile

This generates a Dockerfile that looks similar to:

FROM langchain/langgraphjs-api:20

ADD . /deps/agent

RUN cd /deps/agent && yarn install

ENV LANGSERVE_GRAPHS='{"agent":"./src/react_agent/graph.ts:graph"}'

WORKDIR /deps/agent

RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts

The npx @langchain/langgraph-cli 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.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.