This document provides a high-level introduction to Langflow, explaining its purpose, architecture, and core design. Langflow is an open-source platform for building, deploying, and managing AI-powered workflows and agents through both visual authoring and programmatic APIs. This overview covers the system architecture, package structure, installation methods, and key concepts. For detailed information about specific subsystems, see the System Architecture, Package Structure, and Installation pages.
Sources: README.md1-111 pyproject.toml1-21 docs/docs/Get-Started/get-started-installation.mdx1-179
Langflow is a Python-based platform that enables developers to build AI workflows through a visual flow editor while maintaining full programmatic access. The system consists of three main layers:
The platform supports multiple deployment modes including standalone Desktop application, Docker containers, and Python package installation. Every workflow created in Langflow can be executed via REST API, served as an MCP (Model Context Protocol) server, or embedded in Python applications.
Version: 1.8.0
Python Requirements: >=3.10, <3.14
Default Port: 7860
Sources: README.md16-27 pyproject.toml2-5 src/backend/base/langflow/main.py1-66
Diagram: Core System Architecture showing the relationship between client layer, FastAPI server, backend services, and storage.
The system follows a layered architecture where the FastAPI application src/backend/base/langflow/main.py16 serves as the entry point. The create_app() factory function src/backend/base/langflow/main.py146 initializes all services during the application lifespan. API routes under /api/v1/* src/backend/base/langflow/main.py30 handle all client requests, delegating to specialized services for authentication, database operations, and flow execution.
Sources: src/backend/base/langflow/main.py1-400 pyproject.toml1-50 Makefile16-26
Diagram: Package dependency hierarchy showing the three-tier structure.
Langflow uses a three-tier package architecture to separate concerns and enable modular development:
langflow pyproject.toml2: Top-level package providing the CLI entry point via langflow = "langflow.langflow_launcher:main" pyproject.toml144 Contains minimal code and depends on langflow-base[complete] for functionality.
langflow-base src/backend/base/pyproject.toml2: Core package containing the FastAPI application, services, and component loading system. Includes 60+ dependencies for AI frameworks, databases, and monitoring. Located at src/backend/base/ pyproject.toml83
lfx src/lfx/pyproject.toml2-3: Lightweight executor package providing the component type system, graph processing, and minimal runtime dependencies. Can be used standalone for executing flows without the full Langflow server. Located at src/lfx/ pyproject.toml85
This structure allows developers to use lfx for lightweight execution environments while langflow-base provides the full-featured server with web UI.
Sources: pyproject.toml1-86 src/backend/base/pyproject.toml1-50 src/lfx/pyproject.toml1-49
Diagram: Frontend architecture showing React components, state management with Zustand, and API communication.
The frontend is a single-page application built with React 19 and TypeScript, using Vite for builds src/frontend/package.json108-109 The visual flow editor uses @xyflow/react (v12) src/frontend/package.json43 for the canvas rendering. State is managed through Zustand stores src/frontend/package.json104 with useFlowStore managing the current flow state and useFlowsManagerStore handling flow CRUD operations with 100-state undo/redo history.
API communication uses Axios src/frontend/package.json48 with @tanstack/react-query src/frontend/package.json40 for caching and request deduplication. The ApiInterceptor automatically attaches authentication headers and handles token refresh.
Build Configuration:
vite build src/frontend/package.json109src/frontend/build → copied to src/backend/base/langflow/frontend Makefile106-116vite on port 3000 src/frontend/package.json108StaticFiles("/", directory=path) src/backend/base/langflow/main.py19Sources: src/frontend/package.json1-179 src/frontend/package-lock.json1-150 Makefile106-116
The backend is organized around service-oriented architecture with dependency injection through get_service() and get_settings_service() functions src/backend/base/langflow/main.py41-49
| Service | Type | Purpose | Access Method |
|---|---|---|---|
| SettingsService | Configuration | Loads settings from environment and .env files | get_settings_service() src/backend/base/langflow/main.py43 |
| DatabaseService | Persistence | SQLModel ORM with Alembic migrations | get_service(ServiceType.DATABASE) src/backend/base/langflow/main.py48 |
| AuthService | Security | JWT tokens and API key validation | get_service(ServiceType.AUTH) |
| TelemetryService | Monitoring | Usage tracking and error logging | get_telemetry_service() src/backend/base/langflow/main.py44 |
| MCPComposerService | Integration | Model Context Protocol server management | Initialized in lifespan src/backend/base/langflow/main.py31 |
| QueueService | Task Management | Async task queue for background jobs | get_queue_service() src/backend/base/langflow/main.py42 |
Services are initialized during application startup in initialize_services() src/backend/base/langflow/main.py49 and cleaned up during shutdown in teardown_services() src/backend/base/langflow/main.py49 The lifespan context manager src/backend/base/langflow/main.py146-151 orchestrates the startup sequence:
configure() src/backend/base/langflow/main.py154setup_llm_caching() src/backend/base/langflow/main.py175AUTO_LOGIN=true src/backend/base/langflow/main.py183-189Sources: src/backend/base/langflow/main.py41-232 src/backend/base/pyproject.toml19-98
Diagram: Component system showing registry, loading, and execution flow.
The component system is built around a central registry stored in component_index.json containing metadata for all available components. Each component has:
template.code fieldstable_hash_history.json for version managementComponents are loaded dynamically using eval_custom_component_code() which executes the component's Python code in a controlled environment. The instantiate_class() function creates component instances with proper dependency injection.
When a flow is executed, the backend:
Graph.from_payload() to parse the flow JSON into a graph structureVertex.build() to resolve input values from connected edgesexecute() methodSources: Makefile447-453 docs/docs/Components/components-models.mdx1-150
Langflow supports multiple installation methods, each suited for different use cases:
Standalone desktop application with bundled dependencies for macOS 13+ and Windows. Requires no Python environment management.
Sources: docs/docs/Get-Started/get-started-installation.mdx21-58 README.md29-34
Install via uv (recommended) or pip for maximum flexibility and control:
Requirements:
uv package manager [recommended]The Python package installation provides access to all features and allows customization of the environment. Langflow starts on http://127.0.0.1:7860 by default.
Sources: README.md40-61 docs/docs/Get-Started/get-started-installation.mdx79-161
Pull and run the official Docker image for containerized deployment:
Access Langflow at http://localhost:7860/. For advanced configuration options, see the Docker deployment guide.
Sources: README.md72-78 docs/docs/Get-Started/get-started-installation.mdx62-78
Clone the repository and use the provided Makefile for development:
This builds the frontend, installs dependencies, and starts Langflow with hot reload enabled. For detailed development instructions, see Contributing.
Sources: README.md66-70 Makefile1-500
| Path | Purpose |
|---|---|
src/backend/base/langflow/ | Main backend package with FastAPI app and services |
src/backend/base/langflow/main.py | FastAPI application factory with create_app() |
src/backend/base/langflow/api/ | API route handlers under /api/v1/* |
src/backend/base/langflow/services/ | Service implementations (Auth, Database, Settings, etc.) |
src/frontend/ | React/TypeScript frontend application |
src/frontend/src/controllers/API/ | Frontend API client layer |
src/lfx/src/lfx/ | LFX executor package with component system |
src/lfx/src/lfx/_assets/component_index.json | Component registry |
pyproject.toml | Top-level package configuration for langflow |
src/backend/base/pyproject.toml | Configuration for langflow-base |
src/lfx/pyproject.toml | Configuration for lfx |
Makefile | Build and development commands |
uv.lock | Locked Python dependencies |
src/frontend/package.json | Frontend dependencies and scripts |
Sources: pyproject.toml1-86 Makefile20-27 src/backend/base/langflow/main.py1-50
Langflow uses environment variables for configuration, loaded from .env files or system environment. Key configuration includes:
LANGFLOW_HOST (default: 0.0.0.0), LANGFLOW_PORT (default: 7860)LANGFLOW_AUTO_LOGIN, LANGFLOW_API_KEY_SOURCE, LANGFLOW_WEBHOOK_AUTH_ENABLELANGFLOW_DATABASE_URL for PostgreSQL/SQLite connectionLANGFLOW_LANGFLOW_DIR for data directory (default: ~/.langflow)LANGFLOW_SSRF_PROTECTION_ENABLED, LANGFLOW_SSRF_ALLOWED_HOSTSLANGFLOW_DO_NOT_TRACK to opt-out of usage trackingThe SettingsService src/backend/base/langflow/main.py43 loads configuration during startup. Environment variables must be set before running Langflow.
Configuration File: .env in the project root scripts/setup/setup_env.sh3-10
Sources: scripts/setup/setup_env.sh1-11 src/backend/base/langflow/main.py41-49 docs/docs/Support/release-notes.mdx94-104
Langflow follows a responsible disclosure policy for security vulnerabilities. Recent security updates include:
LANGFLOW_WEBHOOK_AUTH_ENABLE flagReporting: Use the "Report a vulnerability" button under the Security tab on GitHub
Sources: SECURITY.md1-89 docs/docs/Support/release-notes.mdx94-104
The REST API follows a hierarchical structure under /api/v1/:
| Endpoint Prefix | Purpose | Handler Location |
|---|---|---|
/api/v1/flows | Flow CRUD operations | langflow.api.v1.flows |
/api/v1/chat | Flow execution and streaming | langflow.api.v1.chat |
/api/v1/store | Community flows and components | langflow.api.v1.store |
/api/v1/monitor | Observability and metrics | langflow.api.v1.monitor |
/api/v1/files | File upload and management | langflow.api.v1.files |
/api/v1/projects | Project-level operations | langflow.api.v1.projects |
/webhook/{flow_id} | Webhook triggers for flows | langflow.api.webhook |
All routes are registered via router src/backend/base/langflow/main.py30 imported from langflow.api.router. Authentication is handled through middleware and the AuthService.
For detailed API documentation, see the API reference pages #4.3.
Sources: src/backend/base/langflow/main.py29-30 docs/docs/Support/release-notes.mdx94-104
The development environment uses uv for Python dependency management and npm for frontend dependencies:
The Makefile Makefile1-500 provides commands for common development tasks. Backend runs with hot reload via uvicorn --reload Makefile283-304 and frontend uses Vite's HMR for rapid development.
ruff for Python pyproject.toml30 biome for TypeScript src/frontend/package.json141mypy for Python pyproject.toml29 TypeScript compiler for frontendpre-commit install Makefile87pytest for backend, jest for frontend unit tests, Playwright for E2ESources: Makefile38-233 pyproject.toml196-234
Diagram: Build process showing frontend compilation, asset copying, and Python package builds.
The build process follows this sequence:
vite build compiles TypeScript/React to optimized JavaScript bundles in src/frontend/build/src/backend/base/langflow/frontend/ for servinguv build creates lfx wheel at src/lfx/dist/uv build creates langflow-base wheel including frontend assetsuv build creates top-level langflow wheel with CLIBuild command: make build Makefile317-350
Sources: Makefile317-350 src/frontend/package.json108-109
Langflow includes optional telemetry for usage tracking and error reporting:
get_telemetry_service() src/backend/base/langflow/main.py44 tracks eventsLANGFLOW_DO_NOT_TRACK=true to disableopentelemetry-instrumentation-fastapi src/backend/base/pyproject.toml66opentelemetry-exporter-prometheus src/backend/base/pyproject.toml65log_exception_to_telemetry() src/backend/base/langflow/main.py69-76External monitoring integrations available through optional dependencies:
Sources: src/backend/base/langflow/main.py69-76 src/backend/base/pyproject.toml63-67
Langflow includes 15+ pre-built starter projects demonstrating common patterns:
Starter projects are created/updated during application startup via create_or_update_starter_projects() src/backend/base/langflow/main.py33-38 which uses a file lock to prevent duplicate initialization across multiple workers src/backend/base/langflow/main.py213-227
Sources: src/backend/base/langflow/main.py32-38 docs/docs/Support/release-notes.mdx1-50
Langflow provides a file management system for storing and accessing files across flows:
/files endpoint (e.g., http://localhost:7860/files)~/.langflow/ directory (configurable via LANGFLOW_LANGFLOW_DIR)LANGFLOW_MAX_FILE_SIZE_UPLOAD)Files uploaded through the UI or API are accessible to all flows. The Read File component supports multiple formats including PDF, DOCX, CSV, JSON, and more. Advanced parsing is available via the Docling library integration.
Sources: docs/docs/Develop/concepts-file-management.mdx1-150 docs/docs/Components/read-file.mdx1-70 docs/docs/Components/write-file.mdx1-50
Voice mode enables verbal interaction with flows through microphone and speakers (not available in Desktop version):
Voice mode uses OpenAI's speech-to-text and text-to-speech APIs to process audio input and generate audio responses.
Sources: docs/docs/Develop/concepts-voice-mode.mdx1-70
Langflow integrates Model Context Protocol for tool management and inter-agent communication:
MCPComposerService src/backend/base/langflow/main.py31init_mcp_servers() src/backend/base/langflow/main.py31cleanup_mcp_sessions() src/backend/base/langflow/main.py50Sources: src/backend/base/langflow/main.py31-50 docs/docs/Support/release-notes.mdx87-92
For detailed information about specific subsystems:
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.