Langflow User Guide

1. Quick Start

Langflow is a visual framework for building multi-agent AI applications. You design workflows by connecting components on a drag-and-drop canvas — language models, vector stores, tools, document loaders, and hundreds more — then run them from the UI, expose them as APIs, or manage them via the lfx CLI.

Key features:

• Visual flow builder with a React-based canvas (powered by XY Flow)
• 100+ built-in components spanning LLMs, embeddings, vector stores, tools, and agents
• Real-time chat playground for testing flows interactively
• MCP (Model Context Protocol) server integration for tool discovery
• lfx CLI for Flow DevOps: scaffold, validate, push/pull, run, and serve flows
• Agentic experience mode for AI-assisted flow and component operations
• Starter project templates to get productive immediately
• Knowledge base management for RAG workflows

Prerequisites: Python 3.10–3.13, pip or uv, 4 GB RAM minimum.

Install and run:

pip install langflow
langflow run

✓ Initializing Langflow
✓ Checking Environment
✓ Starting Core Services
✓ Connecting Database
✓ Loading Components
✓ Adding Starter Projects
✓ Launching Langflow
╭──────────────────────────────────────────╮
│  Access Langflow: http://localhost:7860   │
╰──────────────────────────────────────────╯

Open http://localhost:7860 in your browser. The first launch creates a local SQLite database and loads starter project templates automatically.

Tip

With AUTO_LOGIN enabled (the default), you are logged in automatically — no credentials needed for local development. See the Configuration section to disable this for shared environments.

What to try next:

• Open a starter project and click Run to see a flow execute
• Try the chat playground to interact with an AI agent flow
• Read Core Usage below for building your first flow from scratch
• See the Admin Guide for full configuration reference and deployment options

2. Installation

System Requirements

Installation Methods

pip (recommended)

pip install langflow

uv

uv pip install langflow

Docker

docker run -p 7860:7860 langflowai/langflow:latest

Docker Compose (with PostgreSQL)

# docker-compose.yml
version: "3.8"
services:
  langflow:
    image: langflowai/langflow:latest
    ports:
      - "7860:7860"
    depends_on:
      - postgres
    environment:
      - LANGFLOW_DATABASE_URL=postgresql://langflow:langflow@postgres:5432/langflow
      - LANGFLOW_CONFIG_DIR=app/langflow
    volumes:
      - langflow-data:/app/langflow
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: langflow
      POSTGRES_PASSWORD: langflow
      POSTGRES_DB: langflow
    ports:
      - "5432:5432"
    volumes:
      - langflow-postgres:/var/lib/postgresql/data
volumes:
  langflow-postgres:
  langflow-data:

docker compose up -d

From source

git clone https://github.com/langflow-ai/langflow.git
cd langflow
make backend

Important

Langflow requires Python 3.10 through 3.13. Python 3.14+ is not yet supported. On Windows, the jq dependency is excluded automatically.

Optional Extras

Langflow uses optional dependency groups for provider-specific integrations. Install only what you need:

Post-Install Verification

langflow run --help

Usage: langflow run [OPTIONS]

  Run Langflow.

langflow run

Then visit http://localhost:7860. You should see the Langflow UI with starter projects in the sidebar.

Warning

If port 7860 is already in use, Langflow will attempt to find an available port. Check the terminal output for the actual URL.

LFX CLI Installation

The lfx CLI is a standalone tool for Flow DevOps — managing flows as code outside the Langflow UI. It is included in the langflow-base package:

pip install langflow-base
lfx --help

Usage: lfx [OPTIONS] COMMAND [ARGS]...

Commands:
  create        Create a new flow JSON from a built-in template
  export        Normalize flow JSON for git (local) or pull from a remote instance
  init          Scaffold a new Flow DevOps project
  login         Validate credentials against a remote Langflow instance
  pull          Pull flows from a remote Langflow instance to local files
  push          Push flow JSON to a remote Langflow instance (upsert by stable ID)
  requirements  Generate requirements.txt for a flow
  run           Run a flow directly
  serve         Serve a flow as an API
  status        Compare local flow files against a remote Langflow instance
  validate      Validate one or more flow JSON files

3. Configuration

Langflow is configured primarily through environment variables prefixed with LANGFLOW_. All settings can also be passed as CLI flags to langflow run.

Essential Settings

Common Configurations

Local development (default):

langflow run
# Equivalent to:
# LANGFLOW_HOST=localhost LANGFLOW_PORT=7860 LANGFLOW_AUTO_LOGIN=true langflow run

Production with PostgreSQL:

export LANGFLOW_DATABASE_URL="postgresql://user:pass@db-host:5432/langflow"
export LANGFLOW_AUTO_LOGIN=false
export LANGFLOW_SUPERUSER=admin
export LANGFLOW_SUPERUSER_PASSWORD=your-secure-password
export LANGFLOW_HOST=0.0.0.0
langflow run

Backend-only (API server, no frontend):

export LANGFLOW_BACKEND_ONLY=true
langflow run

Note

For the complete configuration reference (70+ settings including cache, CORS, MCP, Prometheus, S3 storage, SSO, and SSRF protection), see the Admin Guide.

LFX CLI Configuration

The lfx CLI uses environment files for remote instance connections:

# .lfx/environments.yaml
defaults:
  url: http://localhost:7860
  api_key: ${LANGFLOW_API_KEY}

staging:
  url: https://staging.example.com
  api_key: ${STAGING_API_KEY}

production:
  url: https://langflow.example.com
  api_key: ${PROD_API_KEY}

Set the API key:

export LANGFLOW_API_KEY=your-api-key
# or
export LFX_API_KEY=your-api-key

4. Core Usage

Building Flows in the UI

Langflow's visual canvas lets you build AI workflows by connecting components:

1. Create a new flow — Click New Flow or open a starter project
2. Add components — Drag components from the sidebar onto the canvas. Categories include:
   • Models — OpenAI, Anthropic, Ollama, Google, Groq, Mistral, and more
   • Prompts — Template prompts with variable interpolation
   • Agents — LangChain agents with tool support
   • Tools — Search, calculators, API connectors, MCP tools
   • Vector Stores — Chroma, Pinecone, Qdrant, Weaviate, Milvus, and more
   • Embeddings — OpenAI, Hugging Face, sentence-transformers
   • Document Loaders — PDF, DOCX, web scrapers, YouTube, and more
   • Memory — Conversation buffers, knowledge base retrieval
   • Data — File I/O, data transformation, API data sources
3. Connect components — Drag from an output handle to a compatible input handle
4. Configure components — Click a component to set parameters (API keys, model names, prompts)
5. Run the flow — Click the Run button or use the chat playground

Tip

Use Global Variables (Settings → Global Variables) to store API keys and secrets. Components reference these automatically — no hardcoding credentials in flows.

Using the Chat Playground

The built-in playground lets you interact with flows in real time:

1. Open a flow that has a Chat Input and Chat Output component
2. Click the Playground button in the top-right
3. Type messages and see responses streamed in real time
4. Upload files when the flow supports file inputs
5. View component outputs and intermediate results in the trace panel

Note

The playground creates a session per interaction. Sessions are automatically cleaned up based on the public_flow_cleanup_interval setting (default: 1 hour).

Working with Components

Each component has:

• Input handles (left side) — Accept connections from other components
• Output handles (right side) — Send data to downstream components
• Parameters — Configurable fields (click to edit)
• Tool mode — Toggle to expose the component as a tool for agents

Custom Components:

You can write custom Python components and add them via the LANGFLOW_COMPONENTS_PATH setting:

export LANGFLOW_COMPONENTS_PATH="/path/to/my/components"
langflow run

Warning

When LANGFLOW_ALLOW_CUSTOM_COMPONENTS is set to false, only components matching known server templates will execute. Custom components on the LANGFLOW_COMPONENTS_PATH allow-list are still permitted.

MCP Server Integration

Langflow integrates with the Model Context Protocol (MCP) for tool discovery and execution:

• MCP Tools component — Connect to external MCP servers to use their tools in flows
• Built-in MCP server — Langflow exposes your flows as MCP tools that other clients can call
• MCP Composer — Orchestrate multiple MCP servers from within Langflow

Configure MCP servers in the Langflow UI under Settings → MCP Servers.

Note

When using MCP Tools in lfx serve standalone mode, you may encounter connectivity issues — see Troubleshooting for workarounds (community issue #12759).

Running Flows via API

Every Langflow flow is automatically available as an API endpoint. From the flow editor, click the API button to get code snippets:

import requests

API_URL = "http://localhost:7860/api/v1/run/{flow_id}"
headers = {"x-api-key": "your-api-key"}
payload = {
    "input_value": "Hello, how are you?",
    "output_type": "chat",
    "input_type": "chat"
}

response = requests.post(API_URL, json=payload, headers=headers)
print(response.json())

5. Common Tasks

Task 1: Scaffold a Flow DevOps Project

Goal: Set up a git-tracked project structure for managing Langflow flows as code.

lfx init my-project
cd my-project

✓ Created: flows/
✓ Created: tests/
✓ Created: .lfx/
✓ Created: .lfx/environments.yaml
✓ Created: tests/__init__.py
✓ Created: tests/test_flows.py
✓ Created: .github/workflows/
✓ Created: flows/hello-world.json

Verify:

ls flows/

hello-world.json

Tip

Use lfx init --no-github-actions to skip CI workflow templates, or lfx init --no-example to skip the starter flow.

Task 2: Create a New Flow from a Template

Goal: Scaffold a new flow JSON file.

lfx create "My RAG Flow" --template hello-world --output-dir flows/

Created: flows/my-rag-flow.json

List available templates:

lfx create --list

Task 3: Validate Flows Before Deployment

Goal: Check flow JSON files for structural correctness, component existence, edge compatibility, and required inputs.

lfx validate flows/

✓ flows/hello-world.json: PASS (0 errors, 0 warnings)

Validation levels:

# Strict mode: treat warnings as errors
lfx validate flows/ --strict

# JSON output for CI pipelines
lfx validate flows/ --format json

# Skip specific checks
lfx validate flows/ --skip-credentials --skip-version-check

Task 4: Push Flows to a Remote Langflow Instance

Goal: Deploy local flow files to a running Langflow server.

Prerequisites: Set LANGFLOW_API_KEY and configure .lfx/environments.yaml.

# Push all flows in the flows/ directory
lfx push --dir flows/ --env production

# Push a specific flow
lfx push flows/my-flow.json --env staging

# Dry run to preview changes
lfx push --dir flows/ --env production --dry-run

Important

By default, lfx push normalizes flows (strips volatile fields) and strips secrets before pushing. Use --keep-secrets to push credential values.

Task 5: Pull Flows from a Remote Instance

Goal: Download flows from a Langflow server to local files for version control.

# Pull all flows
lfx pull --env production --output-dir flows/

# Pull a single flow by UUID
lfx pull --flow-id "abc123-def456" --env production

# Pull all flows in a project
lfx pull --project "My Project" --env production

Task 6: Run a Flow from the Command Line

Goal: Execute a flow without starting the full Langflow server.

# Run from a JSON file
lfx run my-flow.json "What is the weather today?"

# Run with verbose output
lfx run my-flow.json "Hello" -v

# Run with timing information
lfx run my-flow.json "Hello" --timing

# Run from stdin
cat my-flow.json | lfx run --stdin "Hello"

# Different output formats
lfx run my-flow.json "Hello" --format text
lfx run my-flow.json "Hello" --format message
lfx run my-flow.json "Hello" --format json

Task 7: Serve a Flow as a Standalone API

Goal: Expose a single flow as a lightweight REST API without the full Langflow UI.

lfx serve my-flow.json --host 0.0.0.0 --port 8000 --verbose

✓ LANGFLOW_API_KEY is configured
╭────────────────────────────────────────────────╮
│  LFX Serve                                     │
│                                                │
│  Flows loaded:  1                              │
│  API docs:      http://0.0.0.0:8000/docs       │
│  Health check:  http://0.0.0.0:8000/health      │
╰────────────────────────────────────────────────╯

Serve API endpoints:

Task 8: Check Flow Sync Status

Goal: See whether local flows match what is deployed on a remote instance.

lfx status --env production

my-flow.json          ▲ ahead (local changes)
other-flow.json       ✓ in sync
new-flow.json         + local only

Use --remote-only to also list flows that exist on the server but have no local file.

Task 9: Export and Normalize Flows for Git

Goal: Strip volatile fields from flow JSON so diffs are clean in version control.

# Normalize in place
lfx export flows/my-flow.json --in-place

# Export to a different directory
lfx export flows/my-flow.json --output-dir normalized/

# Export from remote
lfx export --flow-id "abc123" --env staging --output-dir flows/

Task 10: Generate Requirements for a Flow

Goal: Produce a requirements.txt listing the Python packages a flow needs.

lfx requirements flows/my-flow.json

lfx~=0.4.0
langchain-openai>=1.1.6

# Write to file
lfx requirements flows/my-flow.json --output requirements.txt

# Exclude lfx itself
lfx requirements flows/my-flow.json --no-lfx

# Unpinned versions
lfx requirements flows/my-flow.json --no-pin

Task 11: Set Up Knowledge Bases for RAG

Goal: Create a knowledge base that components can query.

1. In the Langflow UI, navigate to Knowledge in the sidebar
2. Click New Knowledge Base
3. Upload documents (PDF, DOCX, TXT, or web URLs)
4. Select an embedding model and vector store
5. In your flow, use a Knowledge Base Retriever component connected to a prompt

Knowledge bases are stored in the directory specified by LANGFLOW_KNOWLEDGE_BASES_DIR (default: ~/.langflow/knowledge_bases).

Task 12: Authenticate the LFX CLI

Goal: Verify that credentials work before pushing or pulling flows.

# Test default environment
lfx login

# Test a named environment
lfx login --env staging

# Test with inline credentials
lfx login --target https://langflow.example.com --api-key my-key

✓ Connected to https://langflow.example.com
✓ Authenticated — 12 flows available

6. Troubleshooting

Diagnostic Decision Tree

Problem?
├── Can't start Langflow → Check Python version (3.10-3.13), port availability
├── Can't connect → Check LANGFLOW_HOST, firewall, CORS settings
├── Flow won't run → Check component config, API keys, connections
├── LFX CLI errors → Check LANGFLOW_API_KEY, environment config
└── Performance issues → Check worker count, database, cache settings

Error: Port 7860 already in use

Cause: Another process is using the default port.

Solution:

langflow run --port 7861

Or set the environment variable:

export LANGFLOW_PORT=7861

Prevention: Use a dedicated port in your environment configuration.

Error: MCP Tools component fails in lfx serve standalone mode

Cause: The MCP Tools component requires the full Langflow server runtime for proper session management. When serving flows via lfx serve, the MCP session manager may not be fully initialized.

Solution:

1. Use the full langflow run server instead of lfx serve for flows that use MCP Tools
2. Ensure LANGFLOW_MCP_SERVER_ENABLED=true (the default)

Reference: Community issue #12759

Error: MCP Server x-api-key header not propagated to nested calls

Cause: When the MCP server makes nested MCP calls, the x-api-key header is not automatically forwarded to downstream servers.

Solution: Set the API key as a Global Variable and configure each MCP connection to reference it explicitly.

Reference: Community issue #12529

Error: MCP servers gone in container deployments

Cause: MCP server configuration is lost when container restarts because the config directory is not persisted.

Solution:

docker run -v langflow-data:/app/langflow \
  -e LANGFLOW_CONFIG_DIR=/app/langflow \
  -p 7860:7860 langflowai/langflow:latest

Prevention: Always mount a persistent volume for LANGFLOW_CONFIG_DIR.

Reference: Community issue #9524

Error: MCP Server tab fails to load with separate frontend pod in Kubernetes

Cause: The MCP SSE transport requires the correct base URL when the frontend and backend run in separate pods.

Solution: Set LANGFLOW_ROOT_PATH and LANGFLOW_MCP_BASE_URL to match your ingress configuration:

export LANGFLOW_ROOT_PATH=/langflow
export LANGFLOW_MCP_BASE_URL=https://langflow.example.com

Reference: Community issue #10172

Error: MCP tools can't handle number inputs

Cause: The MCP Tools component does not correctly serialize numeric input types.

Solution: Convert numeric inputs to strings in the MCP tool definition, or use a Custom Component wrapper that handles the type conversion.

Reference: Community issue #9424

Error: Custom Component multiple outputs disconnect automatically

Cause: Output type migration from Data→JSON and DataFrame→Table causes connections to drop when component definitions are updated.

Solution: Re-connect the outputs after upgrading. The type names were migrated for consistency; old flows are automatically updated on next load.

Reference: Community issue #12178

Error: Cannot connect to SuperGateway MCP server

Cause: SuperGateway requires specific headers and connection settings that differ from standard MCP SSE servers.

Solution: Verify the server URL format and ensure the Headers field in the MCP server configuration is saved correctly. Prior versions had a bug preventing header saves (fixed in 1.8.x+).

Reference: Community issues #12098, #9579

Error: Custom Component Generator template contains broken URLs

Cause: The auto-generated template for custom components included outdated documentation URLs returning 404 errors.

Solution: Update to the latest Langflow version where template URLs have been corrected.

Reference: Community issue #11716

Error: Shareable Playground strips spaces in input

Cause: A regression in v1.9.0 where the shareable playground trims whitespace from user input.

Solution: Update to a patched version when available. As a workaround, wrap intentional whitespace in code blocks.

Reference: Community issue #12731

Error: If-Else component not responding with stream=true

Cause: Conditional components do not support streaming mode when accessed via the URL API.

Solution: Remove stream=true from the API URL parameters when using conditional components, or use the standard (non-streaming) endpoint.

Reference: Community issue #8103

Error: Deployment in isolated environments fails

Cause: Langflow attempts to download component assets and check for updates on first launch, which fails without internet access.

Solution: Pre-install all dependencies and set:

export LANGFLOW_DO_NOT_TRACK=true
export LANGFLOW_STORE=false

Prevention: Use pip install langflow-base[all] in your CI build step to cache all dependencies.

Reference: Community issue #8043

Error: Gemini with MCP tools sporadically returns 400 errors

Cause: The Google Gemini API returns validation errors when certain MCP tool response formats don't match its expected schema.

Solution: Ensure MCP tool responses return simple string or JSON types. Avoid complex nested objects in tool outputs when using Gemini as the agent LLM.

Reference: Community issue #9437

Error: LANGFLOW_API_KEY not set when using lfx CLI

Cause: The API key environment variable is not exported to child processes.

Solution:

# Wrong (not exported):
LANGFLOW_API_KEY=my-key lfx serve flow.json

# Correct:
export LANGFLOW_API_KEY=my-key
lfx serve flow.json

Both LANGFLOW_API_KEY and LFX_API_KEY are accepted.

Warning

The lfx serve command will exit with code 1 if no API key is configured. This is a security requirement — the key protects your served flow endpoints.

Error: DeprecationWarning: Use apaginate instead

Cause: Internal dependency update; harmless warning from LangChain pagination.

Solution: This warning does not affect functionality. It will be resolved in a future LangChain update.

Reference: Community issue #7951

7. FAQ

Q: What databases does Langflow support?

Langflow uses SQLite by default (zero configuration). For production, PostgreSQL is recommended. Set LANGFLOW_DATABASE_URL to a PostgreSQL connection string. The driver is automatically converted to the async variant (postgresql+psycopg).

Q: How do I disable auto-login for a shared environment?

Set LANGFLOW_AUTO_LOGIN=false and configure a superuser:

export LANGFLOW_AUTO_LOGIN=false
export LANGFLOW_SUPERUSER=admin
export LANGFLOW_SUPERUSER_PASSWORD=your-password

Q: Can I run Langflow without the frontend?

Yes. Set LANGFLOW_BACKEND_ONLY=true to run only the API server. This is useful for headless deployments where flows are managed via the API or lfx CLI.

Q: How do I use a different LLM provider?

Install the provider's optional extra and configure the component in your flow:

pip install langflow-base[anthropic]  # For Claude
pip install langflow-base[ollama]     # For local Ollama
pip install langflow-base[google]     # For Gemini

Then add the corresponding model component to your flow and set the API key as a Global Variable.

Q: What is the difference between langflow run and lfx serve?

langflow run starts the full Langflow server with UI, database, authentication, and all services. lfx serve is a lightweight server that exposes a single flow (or set of flows) as a REST API without the full platform — ideal for production deployment of individual flows.

Q: How do I back up my flows?

Use lfx pull to download all flows to local JSON files:

lfx pull --env production --output-dir backup/

These JSON files can be committed to git. Use lfx push to restore them.

Q: Can I use Langflow behind a reverse proxy?

Yes. Set LANGFLOW_ROOT_PATH to the URL prefix your proxy strips:

export LANGFLOW_ROOT_PATH=/langflow

This ensures the MCP SSE transport and internal routes include the correct prefix.

Q: How do I add custom components?

Create a Python file with your component class and point Langflow to it:

export LANGFLOW_COMPONENTS_PATH="/path/to/custom/components"
langflow run

Components are hot-loaded from the specified path.

Q: What is the MCP Composer?

The MCP Composer orchestrates multiple MCP servers from within Langflow. It runs as a sidecar process using uvx and is enabled by default (LANGFLOW_MCP_COMPOSER_ENABLED=true). The version is controlled by LANGFLOW_MCP_COMPOSER_VERSION (default: 0.1.0.8.10).

Q: How do I monitor Langflow with Prometheus?

Enable metrics collection:

export LANGFLOW_PROMETHEUS_ENABLED=true
export LANGFLOW_PROMETHEUS_PORT=9090
langflow run

Metrics are exposed on the configured port.

Q: What tracing and observability integrations are supported?

Langflow supports multiple tracing backends via optional extras:

• Langfuse — pip install langflow-base[langfuse]
• LangSmith — pip install langflow-base[langsmith]
• LangWatch — pip install langflow-base[langwatch]
• Arize Phoenix — pip install langflow-base[arize]
• Opik — pip install langflow-base[opik]
• Traceloop — pip install langflow-base[traceloop]
• OpenLayer — pip install langflow-base[openlayer]

Configure tracing in the flow editor's trace panel.

Note

The Arize Phoenix tracer converts Data outputs to text, which may prevent structured JSON/dict tracing. See community issue #11738 for updates.

Q: Does Langflow support SSO?

Yes. Set LANGFLOW_SSO_ENABLED=true and configure the provider:

export LANGFLOW_SSO_ENABLED=true
export LANGFLOW_SSO_PROVIDER=oidc  # jwt, oidc, saml, or ldap
export LANGFLOW_SSO_CONFIG_FILE=/path/to/sso-config.yaml

See the Admin Guide for SSO configuration details.

Q: How do I connect Langflow to S3 for file storage?

export LANGFLOW_STORAGE_TYPE=s3
export LANGFLOW_OBJECT_STORAGE_BUCKET_NAME=my-langflow-bucket
export LANGFLOW_OBJECT_STORAGE_PREFIX=files

Q: Can I use Langflow with Celery for background task processing?

Yes. Enable Celery and configure the broker:

export LANGFLOW_CELERY_ENABLED=true
export LANGFLOW_REDIS_HOST=redis-host
export LANGFLOW_REDIS_PORT=6379

See the Admin Guide for full Celery and Redis configuration.

Q: What version of Python does the frontend require for development?

The frontend is a React/TypeScript application and requires Node.js 20.19.0 or later (22.x recommended). Python is not required for frontend development.