LangGraph CLI

0.4.21 · active · verified Thu Apr 09

The `langgraph-cli` is a command-line interface tool designed to interact with the LangGraph API, primarily for deploying, managing, and running LangGraph applications. It enables developers to build, deploy, and validate LangGraph applications to various environments. The current version is 0.4.21, and it's actively developed with frequent releases, often alongside updates to the core `langgraph` library.

Common errors

```
ModuleNotFoundError: No module named 'typing_extensions'
```
cause The `langgraph-cli` (specifically version 0.4.21 and potentially other 0.4.x releases) uses `typing_extensions` internally but does not explicitly declare it as a dependency in its package metadata, leading to its absence in clean Python environments.

fix Manually install the missing dependency: `pip install typing_extensions`.
```
'langgraph' is not recognized as the name of a cmdlet, function, script file, or operable program.
```
cause The `langgraph` command-line executable is not in your system's PATH, or you are running the command outside of an activated Python virtual environment where `langgraph-cli` was installed. This is a common occurrence on Windows systems.

fix Activate your Python virtual environment if you are using one. If the issue persists or if you are not using a virtual environment, ensure `langgraph-cli` is installed and its script directory is in your system's PATH, or execute the command using `python -m langgraph_cli <command>` (e.g., `python -m langgraph_cli dev`).
```
ModuleNotFoundError: No module named 'your_project_module' (during `langgraph up` or `langgraph deploy`)
```
cause During the `langgraph up` or `langgraph deploy` process, the CLI builds a Docker image. This error indicates that a Python module from your local project, which is a dependency for your LangGraph application, cannot be found within the Docker build context. This usually means the `langgraph.json` `dependencies` field is not correctly configured or the local package is not properly installed within the build environment.

fix Ensure your `langgraph.json` configuration file correctly specifies your local package as a dependency, typically by including `'.'` in the `dependencies` array (e.g., `"dependencies": [".", "langchain_openai"]`). Also, verify that your local package is installable (e.g., via `pyproject.toml` or `requirements.txt`).
```
Failed to initialize Studio - Please verify if the API server is running or accessible from the browser. TypeError: Failed to fetch
```
cause This error occurs when LangSmith Studio (served over HTTPS) attempts to connect to your local `langgraph dev` server, which typically runs on HTTP. Recent browser security updates (e.g., Chrome 142) enforce Private Network Access (PNA), blocking HTTPS sites from accessing HTTP localhost resources by default.

fix In your browser's site settings for `https://smith.langchain.com`, explicitly allow 'Local network access'. Alternatively, run your `langgraph dev` server with the `--tunnel` flag (e.g., `langgraph dev --tunnel`) to create a secure, publicly accessible URL for Studio to connect to.
```
NotImplementedError: `add_signal_handler` is not implemented for this event loop on Windows
```
cause The `langgraph up` command relies on `asyncio` signal handlers for managing processes and graceful shutdowns. The default `asyncio` event loop on Windows does not implement these signal handlers, leading to this error when trying to run `langgraph up` directly on Windows.

fix Run `langgraph up` within a Windows Subsystem for Linux (WSL2) environment, which provides a Linux-compatible environment where `asyncio` signal handlers are supported. Alternatively, some users have reported success with platform-specific workarounds or by using `uvloop` on Windows, but WSL2 is the most robust solution.

Warnings

gotcha The `langgraph-cli` is distinct from the `langgraph` Python library. The CLI is used for deploying and interacting with *deployed* LangGraph applications, not for authoring or running local Python `langgraph` code directly. Users often confuse the two.
Fix: Understand that the CLI operates on deployed services. For local development, use the `langgraph` Python package. For interacting with remote deployments, use the CLI.
gotcha Deploying LangGraph applications with `langgraph deploy` often requires external dependencies like Docker or specific cloud provider credentials (e.g., for AWS ECS/Lambda, GCP Cloud Run). The CLI itself doesn't bundle these dependencies.
Fix: Ensure your environment is set up with Docker and relevant cloud SDKs/credentials before attempting `langgraph deploy` commands. Refer to the official LangGraph documentation for deployment prerequisites.
breaking CLI command arguments and subcommands can change between minor versions. For instance, the `deploy` subcommands, or available flags, may be modified or renamed. New commands like `validate` are added incrementally.
Fix: Always consult the `langgraph <command> --help` output or the official documentation for the specific version you are using, especially after updating the CLI.
gotcha When interacting with remote LangGraph applications (e.g., using `langgraph run`), you need to configure access via environment variables like `LANGCHAIN_API_KEY` and `LANGCHAIN_ENDPOINT`.
Fix: Set `LANGCHAIN_API_KEY` and `LANGCHAIN_ENDPOINT` environment variables in your shell before running commands that interact with remote LangGraph deployments. Example: `export LANGCHAIN_API_KEY='...'`.

Install

pip install langgraph-cli Install LangGraph CLI

Quickstart

The `langgraph-cli` is a command-line utility, so it's not imported in Python code. This quickstart demonstrates how to check its installation and view available commands.

langgraph --help

view raw JSON →