Back to Details

langgraph-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<overview> The `langgraph` CLI manages the full lifecycle of LangGraph applications — from scaffolding a new project to deploying it to LangGraph Platform (LangSmith Deployments).
Key commands:
  • langgraph new
     — Scaffold a project from a template
  • langgraph dev
     — Run locally with hot reload (no Docker)
  • langgraph build
     — Build a Docker image
  • langgraph up
     — Launch locally via Docker Compose
  • langgraph deploy
     — Ship to LangGraph Platform
  • langgraph dockerfile
     — Generate a Dockerfile
All commands (except 
new
) read from a 
langgraph.json
config file in the project root. </overview>
<overview> `langgraph` CLI 管理LangGraph应用的完整生命周期——从搭建新项目到部署至LangGraph Platform（LangSmith Deployments）。
核心命令：
  • langgraph new
     — 从模板搭建项目
  • langgraph dev
     — 本地运行并支持热重载（无需Docker）
  • langgraph build
     — 构建Docker镜像
  • langgraph up
     — 通过Docker Compose本地启动
  • langgraph deploy
     — 部署至LangGraph Platform
  • langgraph dockerfile
     — 生成Dockerfile
所有命令（除
new
外）都会读取项目根目录下的
langgraph.json
配置文件。 </overview>

When to use

适用场景

Use this skill when the user wants to:
  • Scaffold a new LangGraph project
  • Run a local development or production-like server
  • Build or deploy a LangGraph application
  • Understand or edit 
    langgraph.json
    configuration
  • Manage LangSmith Deployments (list, delete, view logs)
当用户有以下需求时使用此Skill：
  • 搭建新的LangGraph项目
  • 运行本地开发或类生产环境服务器
  • 构建或部署LangGraph应用
  • 理解或编辑
    langgraph.json
    配置
  • 管理LangSmith Deployments（列出、删除、查看日志）

Installation

安装方法

bash
undefined
bash
undefined

Python

Python

pip install 'langgraph-cli[inmem]' # includes langgraph dev support pip install langgraph-cli # without dev server (build/up/deploy only)
pip install 'langgraph-cli[inmem]' # 包含langgraph dev支持 pip install langgraph-cli # 不包含开发服务器（仅支持build/up/deploy）

if using UV as package manager

若使用UV作为包管理器

uv add "langgraph-cli[inmem]" # includes langgraph dev support uv add langgraph-cli # without dev server (build/up/deploy only)
uv add "langgraph-cli[inmem]" # 包含langgraph dev支持 uv add langgraph-cli # 不包含开发服务器（仅支持build/up/deploy）

JavaScript

JavaScript

npx @langchain/langgraph-cli # use on demand npm install -g @langchain/langgraph-cli # install globally (available as langgraphjs)
undefined
npx @langchain/langgraph-cli # 按需使用 npm install -g @langchain/langgraph-cli # 全局安装（可通过langgraphjs调用）
undefined

Commands

命令说明

langgraph new [PATH]

langgraph new [PATH]

Scaffold a new project from a template.
bash
langgraph new                          # interactive template selection
langgraph new ./my-agent               # create in specific directory
langgraph new --template agent-python  # skip prompt, use template directly
Available templates: 
deep-agent-python
, 
deep-agent-js
, 
agent-python
, 
new-langgraph-project-python
, 
new-langgraph-project-js
从模板搭建新项目。
bash
langgraph new                          # 交互式选择模板
langgraph new ./my-agent               # 在指定目录创建
langgraph new --template agent-python  # 跳过提示，直接使用指定模板
可用模板：
deep-agent-python
, 
deep-agent-js
, 
agent-python
, 
new-langgraph-project-python
, 
new-langgraph-project-js

langgraph dev

langgraph dev

Run a local development server with hot reloading. No Docker required.
bash
langgraph dev                              # default: localhost:2024
langgraph dev --port 8000                  # custom port
langgraph dev --config ./langgraph.json    # explicit config path
langgraph dev --no-reload                  # disable hot reload
langgraph dev --no-browser                 # don't auto-open LangGraph Studio
langgraph dev --host 0.0.0.0              # bind to all interfaces (trusted networks only)
langgraph dev --tunnel                     # expose via Cloudflare tunnel for remote access
langgraph dev --debug-port 5678            # enable remote debugger (requires debugpy)
langgraph dev --n-jobs-per-worker 20       # max concurrent jobs per worker (default: 10)
运行带热重载的本地开发服务器，无需Docker。
bash
langgraph dev                              # 默认地址：localhost:2024
langgraph dev --port 8000                  # 自定义端口
langgraph dev --config ./langgraph.json    # 指定配置文件路径
langgraph dev --no-reload                  # 禁用热重载
langgraph dev --no-browser                 # 不自动打开LangGraph Studio
langgraph dev --host 0.0.0.0              # 绑定至所有网络接口（仅信任网络环境下使用）
langgraph dev --tunnel                     # 通过Cloudflare隧道暴露服务以实现远程访问
langgraph dev --debug-port 5678            # 启用远程调试器（需安装debugpy）
langgraph dev --n-jobs-per-worker 20       # 每个工作进程的最大并发任务数（默认：10）

langgraph build

langgraph build

Build a Docker image for the LangGraph API server.
bash
langgraph build -t my-image                # required: tag the image
langgraph build -t my-image --no-pull      # use locally-built base images
langgraph build -t my-image -c langgraph.json  # explicit config
langgraph build -t my-image --base-image langchain/langgraph-server:0.2.18  # pin base version
为LangGraph API服务器构建Docker镜像。
bash
langgraph build -t my-image                # 必填：为镜像打标签
langgraph build -t my-image --no-pull      # 使用本地构建的基础镜像
langgraph build -t my-image -c langgraph.json  # 指定配置文件
langgraph build -t my-image --base-image langchain/langgraph-server:0.2.18  # 固定基础镜像版本

langgraph up

langgraph up

Launch the LangGraph API server via Docker Compose (includes Postgres).
bash
langgraph up                               # default port 8123
langgraph up --port 8000                   # custom port
langgraph up --watch                       # restart on file changes
langgraph up --recreate                    # force fresh build (useful for pre-deploy validation)
langgraph up --postgres-uri postgresql://...  # external Postgres
langgraph up --no-pull                     # use local images (after langgraph build)
langgraph up --image my-image              # skip build, use pre-built image
langgraph up -d docker-compose.yml         # add extra Docker services
langgraph up --debugger-port 8124          # serve debugger UI
langgraph up --wait                        # block until services are healthy
通过Docker Compose启动LangGraph API服务器（包含Postgres）。
bash
langgraph up                               # 默认端口8123
langgraph up --port 8000                   # 自定义端口
langgraph up --watch                       # 文件变更时重启服务
langgraph up --recreate                    # 强制重新构建（部署前验证时实用）
langgraph up --postgres-uri postgresql://...  # 使用外部Postgres
langgraph up --no-pull                     # 使用本地镜像（执行langgraph build后）
langgraph up --image my-image              # 跳过构建，使用预构建镜像
langgraph up -d docker-compose.yml         # 添加额外Docker服务
langgraph up --debugger-port 8124          # 启动调试器UI
langgraph up --wait                        # 阻塞直到服务健康

langgraph deploy

langgraph deploy

Build and deploy to LangGraph Platform (LangSmith Deployments). Requires Docker. On Apple Silicon (M1/M2/M3), Docker Buildx is also required for cross-compiling to 
linux/amd64
.
bash
langgraph deploy                           # deploy, name defaults to directory name
langgraph deploy --name my-agent           # explicit deployment name
langgraph deploy --deployment-type prod    # production deployment (default: dev)
langgraph deploy --tag v1.2.0              # custom image tag (default: latest)
langgraph deploy --deployment-id <id>      # update an existing deployment by ID
langgraph deploy --config ./langgraph.json # explicit config path
langgraph deploy --no-wait                 # don't wait for deployment status
langgraph deploy --verbose                 # show detailed server logs
Prereq: 
LANGSMITH_API_KEY
in environment or 
.env
.
langgraph deploy
also accepts build flags: 
--base-image
, 
--pull
/
--no-pull
.
构建并部署至LangGraph Platform（LangSmith Deployments），需Docker。在Apple Silicon（M1/M2/M3）设备上，还需Docker Buildx以交叉编译至
linux/amd64
架构。
bash
langgraph deploy                           # 部署，名称默认使用目录名
langgraph deploy --name my-agent           # 指定部署名称
langgraph deploy --deployment-type prod    # 生产环境部署（默认：开发环境）
langgraph deploy --tag v1.2.0              # 自定义镜像标签（默认：latest）
langgraph deploy --deployment-id <id>      # 通过ID更新现有部署
langgraph deploy --config ./langgraph.json # 指定配置文件路径
langgraph deploy --no-wait                 # 不等待部署状态
langgraph deploy --verbose                 # 显示详细服务器日志
前置要求：环境变量或
.env
文件中需配置
LANGSMITH_API_KEY
。
langgraph deploy
同样支持构建参数：
--base-image
, 
--pull
/
--no-pull
。

langgraph deploy list

langgraph deploy list

bash
langgraph deploy list                      # list all deployments
langgraph deploy list --name-contains bot  # filter by name
bash
langgraph deploy list                      # 列出所有部署
langgraph deploy list --name-contains bot  # 按名称过滤

langgraph deploy delete

langgraph deploy delete

bash
langgraph deploy delete <deployment-id>          # interactive confirmation
langgraph deploy delete <deployment-id> --force  # skip confirmation
bash
langgraph deploy delete <deployment-id>          # 交互式确认删除
langgraph deploy delete <deployment-id> --force  # 跳过确认直接删除

langgraph deploy logs

langgraph deploy logs

bash
langgraph deploy logs                                  # runtime logs, last 100
langgraph deploy logs --name my-agent                  # by deployment name
langgraph deploy logs --deployment-id <id>             # by deployment ID
langgraph deploy logs --type build                     # build logs instead of runtime
langgraph deploy logs -f                               # follow/stream logs
langgraph deploy logs --level error                    # filter by level (debug|info|warning|error|critical)
langgraph deploy logs -q "timeout"                     # search filter
langgraph deploy logs --limit 500                      # more entries
langgraph deploy logs --start-time 2026-03-08T00:00:00Z  # time range
bash
langgraph deploy logs                                  # 运行时日志，默认显示最近100条
langgraph deploy logs --name my-agent                  # 按部署名称查看
langgraph deploy logs --deployment-id <id>             # 按部署ID查看
langgraph deploy logs --type build                     # 查看构建日志而非运行时日志
langgraph deploy logs -f                               # 实时跟踪日志
langgraph deploy logs --level error                    # 按级别过滤（debug|info|warning|error|critical）
langgraph deploy logs -q "timeout"                     # 搜索过滤
langgraph deploy logs --limit 500                      # 显示更多条目
langgraph deploy logs --start-time 2026-03-08T00:00:00Z  # 按时间范围过滤

langgraph dockerfile <SAVE_PATH>

langgraph dockerfile <SAVE_PATH>

Generate a Dockerfile (and optionally Docker Compose files) without building.
bash
langgraph dockerfile ./Dockerfile                      # generate Dockerfile
langgraph dockerfile ./Dockerfile --add-docker-compose # also generate compose + .env + .dockerignore
生成Dockerfile（可选生成Docker Compose文件）但不执行构建。
bash
langgraph dockerfile ./Dockerfile                      # 生成Dockerfile
langgraph dockerfile ./Dockerfile --add-docker-compose # 同时生成compose、.env和.dockerignore文件

langgraph.json
reference

langgraph.json
参考

The configuration file used by all CLI commands (
dev
, 
build
, 
up
, 
deploy
). Defaults to 
langgraph.json
in the current directory.
所有CLI命令（
dev
, 
build
, 
up
, 
deploy
）使用的配置文件，默认读取当前目录下的
langgraph.json
。

Minimal config (Python)

Python极简配置

json
{
    "dependencies": ["."],
    "graphs": {
        "agent": "./my_agent/agent.py:graph"
    },
    "env": "./.env"
}
json
{
    "dependencies": [".."],
    "graphs": {
        "agent": "./my_agent/agent.py:graph"
    },
    "env": "./.env"
}

Minimal config (JavaScript)

JavaScript极简配置

json
{
    "dependencies": ["."],
    "graphs": {
        "agent": "./src/agent.js:graph"
    },
    "env": "./.env"
}
json
{
    "dependencies": [".."],
    "graphs": {
        "agent": "./src/agent.js:graph"
    },
    "env": "./.env"
}

Full config with all keys

包含所有配置项的完整配置

json
{
    "dependencies": [".", "langchain_openai", "./local_package"],
    "graphs": {
        "agent": "./my_agent/agent.py:graph",
        "retriever": "./my_agent/rag.py:rag_graph"
    },
    "env": "./.env",
    "python_version": "3.12",
    "pip_config_file": "./pip.conf",
    "dockerfile_lines": [
        "RUN apt-get update && apt-get install -y ffmpeg"
    ]
}
json
{
    "dependencies": ["..", "langchain_openai", "./local_package"],
    "graphs": {
        "agent": "./my_agent/agent.py:graph",
        "retriever": "./my_agent/rag.py:rag_graph"
    },
    "env": "./.env",
    "python_version": "3.12",
    "pip_config_file": "./pip.conf",
    "dockerfile_lines": [
        "RUN apt-get update && apt-get install -y ffmpeg"
    ]
}

Key reference

配置项说明

KeyRequiredDescription
dependencies
YesArray of dependencies. 
"."
looks for local packages via 
pyproject.toml
, 
setup.py
, 
requirements.txt
, or 
package.json
. Can also be paths to subdirectories (
"./my_pkg"
) or package names (
"langchain_openai"
).
graphs
YesMapping of graph ID to path. Format: 
./path/to/file.py:variable
(Python) or 
./path/to/file.js:function
(JS). The variable must be a 
CompiledGraph
or a function returning one. Multiple graphs supported.
env
NoPath to a 
.env
file (string) OR an inline mapping of env var names to values (object). Used by 
langgraph dev
and 
langgraph up
locally. 
langgraph deploy
reads from this file and adds the variables as deployment secrets.
python_version
No
"3.11"
, 
"3.12"
, or 
"3.13"
. Defaults to 
"3.11"
.
node_version
NoNode.js version for JS projects.
pip_config_file
NoPath to a pip config file for custom package indexes.
dockerfile_lines
NoArray of additional Dockerfile lines appended after the base image import. Use for system packages, binaries, or custom setup.
配置项是否必填描述
dependencies
是依赖项数组。
".."
通过
pyproject.toml
、
setup.py
、
requirements.txt
或
package.json
查找本地包。也可以是子目录路径（
"./my_pkg"
）或包名（
"langchain_openai"
）。
graphs
是图ID到路径的映射。格式：
./path/to/file.py:variable
（Python）或
./path/to/file.js:function
（JS）。变量必须是
CompiledGraph
或返回该类型的函数。支持多个图。
env
否
.env
文件路径（字符串）或环境变量名与值的内联映射（对象）。本地运行
langgraph dev
和
langgraph up
时使用。
langgraph deploy
会读取该文件并将变量添加为部署密钥。
python_version
否
"3.11"
、
"3.12"
或
"3.13"
，默认值为
"3.11"
。
node_version
否JS项目使用的Node.js版本。
pip_config_file
否自定义包索引的pip配置文件路径。
dockerfile_lines
否附加到基础镜像导入后的Dockerfile行数组。用于安装系统包、二进制文件或自定义设置。

Typical workflow

典型工作流程

  1. Scaffold — 
    langgraph new
    to create a project from a template.
  2. Configure — Edit 
    langgraph.json
    : set dependencies, point 
    graphs
    at your compiled graph(s), add 
    .env
    .
  3. Develop — 
    langgraph dev
    for rapid local iteration with hot reload (no Docker, port 2024).
  4. Validate — 
    langgraph up --recreate
    to test in a production-like Docker stack (port 8123, includes Postgres).
  5. Deploy — 
    langgraph deploy
    to ship to LangGraph Platform (LangSmith Deployments).
  6. Monitor — 
    langgraph deploy logs -f
    to tail runtime logs; 
    --type build
    for build logs.
  1. 搭建 — 使用
    langgraph new
    从模板创建项目。
  2. 配置 — 编辑
    langgraph.json
    ：设置依赖项，将
    graphs
    指向已编译的图，添加
    .env
    文件。
  3. 开发 — 使用
    langgraph dev
    进行快速本地迭代，支持热重载（无需Docker，端口2024）。
  4. 验证 — 使用
    langgraph up --recreate
    在类生产环境的Docker栈中测试（端口8123，包含Postgres）。
  5. 部署 — 使用
    langgraph deploy
    部署至LangGraph Platform（LangSmith Deployments）。
  6. 监控 — 使用
    langgraph deploy logs -f
    跟踪运行时日志；使用
    --type build
    查看构建日志。

langgraph dev
vs 
langgraph up

langgraph dev
与
langgraph up
对比

Feature
langgraph dev
langgraph up
Docker requiredNoYes
Install
pip install 'langgraph-cli[inmem]'
pip install langgraph-cli
Primary useRapid development & testingProduction-like validation
State persistenceIn-memory / pickled to local dirPostgreSQL
Hot reloadingYes (default)Optional (
--watch
)
Default port20248123
Resource usageLightweightHeavier (Docker containers for server, Postgres, Redis)
IDE debuggingBuilt-in DAP support (
--debug-port
)		Container debugging
特性
langgraph dev
langgraph up
是否需要Docker否是
安装命令
pip install 'langgraph-cli[inmem]'
pip install langgraph-cli
主要用途快速开发与测试类生产环境验证
状态持久化内存存储 / 本地目录序列化PostgreSQL
热重载是（默认开启）可选（
--watch
参数）
默认端口20248123
资源占用轻量较重（服务器、Postgres、Redis的Docker容器）
IDE调试内置DAP支持（
--debug-port
参数）		容器调试

Gotchas

注意事项

  • langgraph deploy
    requires Docker     — On Apple Silicon (M1/M2/M3), Docker Buildx is also required for cross-compiling to 
    linux/amd64
    .
  • langgraph deploy
    can only update its own deployments     — Deployments created through the LangSmith UI or GitHub integration cannot be updated with 
    langgraph deploy
    . Use the UI for those.
  • dependencies
    must include all packages     — The 
    dependencies
    array in 
    langgraph.json
    must point to where your package config lives (e.g., 
    "."
    for root). The actual packages are resolved from 
    pyproject.toml
    , 
    requirements.txt
    , or 
    package.json
    at that location.
  • langgraph dev
    runs without Docker     — It runs directly in your environment. If your code depends on system packages (e.g., 
    ffmpeg
    ), they must be installed locally. Use 
    langgraph up
    to validate Docker builds.
  • JavaScript CLI — Use 
    npx @langchain/langgraph-cli <command>
    (or 
    langgraphjs
    if installed globally via 
    npm install -g @langchain/langgraph-cli
    ).
  • API key — 
    LANGSMITH_API_KEY
    is required for 
    langgraph deploy
    . For 
    langgraph dev
    , it is optional — the server runs without it, but you won't get traces in LangSmith. Can also be set via 
    LANGGRAPH_HOST_API_KEY
    or 
    LANGCHAIN_API_KEY
    .
  • langgraph deploy
    需要Docker     — 在Apple Silicon（M1/M2/M3）设备上，还需Docker Buildx以交叉编译至
    linux/amd64
    架构。
  • langgraph deploy
    仅能更新自身创建的部署     — 通过LangSmith UI或GitHub集成创建的部署无法使用
    langgraph deploy
    更新，需通过UI操作。
  • dependencies
    必须包含所有包     — 
    langgraph.json
    中的
    dependencies
    数组必须指向包配置所在位置（例如根目录的
    ".."
    ）。实际包会从该位置的
    pyproject.toml
    、
    requirements.txt
    或
    package.json
    解析。
  • langgraph dev
    无需Docker运行     — 直接在本地环境运行。若代码依赖系统包（如
    ffmpeg
    ），需在本地安装。使用
    langgraph up
    验证Docker构建。
  • JavaScript CLI — 使用
    npx @langchain/langgraph-cli <command>
    （若通过
    npm install -g @langchain/langgraph-cli
    全局安装，可使用
    langgraphjs
    调用）。
  • API密钥 — 
    langgraph deploy
    需要
    LANGSMITH_API_KEY
    。
    langgraph dev
    可选配置该密钥——无密钥时服务器可运行，但无法在LangSmith中查看跟踪数据。也可通过
    LANGGRAPH_HOST_API_KEY
    或
    LANGCHAIN_API_KEY
    设置。