LangGraph Local Setup on Mac: A Complete Beginner’s Guide

If you want to build AI agents that actually hold state, loop, branch and recover from failure, LangGraph is where most developers end up. But before you write a single node, you need a working local environment — and that is where a lot of people stall out, usually on a Python version mismatch or a command copied from an outdated tutorial.

This guide walks through a clean LangGraph install on macOS from scratch. By the end you will have an isolated Python environment, the LangGraph CLI, a starter project generated from an official template, and a local dev server running with a visual debugger attached in your browser.

Budget about fifteen minutes.

What you’ll need before you start

A Mac running a recent version of macOS, on either Apple Silicon or Intel — both work fine. You’ll need Python 3.11 or newer, which matters more than it sounds: macOS ships with an older system Python, and the in-memory LangGraph server will refuse to install on it. You’ll also want Homebrew for installing Python if yours is out of date, and comfort with basic Terminal commands.

Optionally, have an OpenAI API key ready if you plan to wire up a language model, plus a free LangSmith account if you want tracing and the visual debugger.

Step 1: Check your Python version

Start here. Skipping this check is the single most common reason the install fails halfway through.

python3 --version

If that prints 3.11 or higher, move on. If it prints something older, install a newer Python with Homebrew:

brew install python@3.12

Step 2: Create and activate a virtual environment

A virtual environment keeps LangGraph and its dependencies isolated from your system Python, so a version bump in one project can’t break another. Create one inside your project folder:

python3 -m venv langgraph-env
source langgraph-env/bin/activate

The name langgraph-env is arbitrary — call it .venv, rag, or whatever fits your convention. Once it’s active, your prompt will be prefixed with the environment name, which is your confirmation that everything you install next lands inside the sandbox rather than in your system Python.

If you installed a specific Python version in Step 1, point the command at it directly: python3.12 -m venv langgraph-env.

To leave the environment later, run deactivate. You’ll need to re-run the source command every time you open a new Terminal tab.

Step 3: Install LangGraph and the core libraries

With the environment active, install the framework itself:

pip install -U langgraph

Then add LangChain and the OpenAI integration. LangGraph handles orchestration — the state machine, the routing, the persistence — while LangChain supplies the model wrappers, tools and message types you’ll build nodes around:

pip install -U langchain langchain-openai

Using a different provider? Swap in langchain-anthropic for Claude or langchain-google-genai for Gemini. Nothing about the LangGraph setup changes.

Step 4: Install the LangGraph CLI and local server

The CLI is what scaffolds projects and runs the local development server. The [inmem] extra is the important part — it pulls in the in-memory server that lets you run agents locally without Docker or a Postgres instance:

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

Keep the quotes. In zsh — the default Mac shell — square brackets are glob characters, and an unquoted langgraph-cli[inmem] will fail with a “no matches found” error. Also make sure you’re typing straight quotes, not the curly quotes a word processor or CMS might have substituted.

Confirm it landed:

langgraph --help

You should see the available commands, including new, dev and build. If you get command not found, your virtual environment probably isn’t active — check for the prefix in your prompt and re-run the source command from Step 2.

Step 5: Create your project from a template

Rather than assembling a project layout by hand, generate one:

langgraph new my-agent-project --template new-langgraph-project-python

Note the double hyphen in --template. If you copied that command from a blog post and it errored out, a single en dash is very often the culprit.

Run langgraph new with no arguments and you’ll get an interactive menu of templates instead, including a ready-made ReAct agent if you’d rather start from something with more scaffolding than a bare graph.

The generated folder includes your graph definition, a langgraph.json config file that tells the server which graph to load, a pyproject.toml, and a .env.example to copy.

Step 6: Install the project’s dependencies

Move into the new folder and install it as an editable package:

cd my-agent-project
pip install -e .

The -e flag means editable mode: Python reads your source files directly instead of copying them into site-packages, so your edits take effect immediately without a reinstall. This step also pulls in whatever dependencies the template declared.

Step 7: Add your API keys

Here’s where most first runs fall over. The template ships an example env file, not a real one — so copy it:

cp .env.example .env

Open .env and fill in the values. Add your model key if your graph calls an LLM:

OPENAI_API_KEY=your-key-here

And add a LangSmith key if you want traces of every run, which is genuinely worth having when you’re debugging why an agent looped four times:

LANGSMITH_API_KEY=your-key-here

Never commit this file. Confirm .env is listed in your .gitignore before your first push.

Step 8: Launch the dev server

From inside the project folder:

langgraph dev

This starts the in-memory server on port 2024 and prints a set of URLs — the API at http://127.0.0.1:2024, interactive API docs at /docs, and a Studio link that opens the visual debugger in your browser. Studio is the payoff: you can see your graph rendered as a diagram, step through execution node by node, inspect state at each hop, and edit past state to re-run from the middle of a conversation.

The server hot-reloads, so you can leave it running while you edit your graph.

One Mac-specific gotcha: Safari and Brave block requests from an HTTPS page to localhost, which breaks the Studio connection. Use Chrome, or start the server with langgraph dev --tunnel to route around it.

A note about the LangGraph Studio desktop app

If you’ve followed an older tutorial, you may have seen this command:

brew install --cask langgraph-studio

Skip it. The standalone macOS desktop app has been discontinued in favour of the browser-based Studio that langgraph dev opens for you. There’s nothing extra to install — Step 8 already gave you the debugger. If that Homebrew command failed for you, that’s why, and nothing is wrong with your setup.

Tips for a smoother setup

Create one virtual environment per project rather than reusing a single global one; agent frameworks move fast, and pinning per project saves you from surprise breakages. If port 2024 is already occupied, pass --port 2025 to langgraph dev. And when you hit an externally-managed-environment error from pip, that’s a reliable signal you’re installing outside your virtual environment — activate it and try again rather than reaching for --break-system-packages.

Wrapping up

That’s a complete local LangGraph environment: isolated dependencies, the CLI, a scaffolded project, and a hot-reloading server with a visual debugger. The next step is opening your graph file and adding a node that actually calls a model — with Studio already running, you’ll be able to watch state move through it as you build.

If you found this useful, subscribe for more practical walkthroughs on building AI agents — no fluff, just setups that work.