From 0c9d3781617150cb0277f69ce5078899af6a0e2b Mon Sep 17 00:00:00 2001
From: Mendon Kissling <59585235+mendonk@users.noreply.github.com>
Date: Fri, 20 Jun 2025 17:34:46 -0400
Subject: [PATCH] docs: refactor installation page (#8487)
* initial-changes
* install-by-os
* powershell-install-and-venvs
* clearer-intro
* post-install-and-ordering
* readme quickstart
* run
* Apply suggestions from code review
Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>
* Apply suggestions from code review
Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>
* Apply suggestions from code review
Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>
Co-authored-by: KimberlyFields <46325568+KimberlyFields@users.noreply.github.com>
* Apply suggestions from code review
Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>
* Apply suggestions from code review
Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>
* Apply suggestions from code review
Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>
* Apply suggestions from code review
Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>
* dependency-extras
* move-troubleshooting-to-details-tabs
* manage-versions-tabs
* left-align
* Apply suggestions from code review
Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>
* add-venv-deactivate-why
---------
Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>
Co-authored-by: KimberlyFields <46325568+KimberlyFields@users.noreply.github.com>
---
README.md | 34 +-
.../Get-Started/get-started-installation.md | 307 +++++++++---------
2 files changed, 173 insertions(+), 168 deletions(-)
diff --git a/README.md b/README.md
index 4defe25b5..ddddd91c0 100644
--- a/README.md
+++ b/README.md
@@ -19,39 +19,37 @@
## ✨ Highlight features
-1. **Visual Builder** to get started quickly and iterate.
-1. **Access to Code** so developers can tweak any component using Python.
-1. **Playground** to immediately test and iterate on their flows with step-by-step control.
-1. **Multi-agent** orchestration and conversation management and retrieval.
-1. **Deploy as an API** or export as JSON for Python apps.
-1. **Observability** with LangSmith, LangFuse and other integrations.
-1. **Enterprise-ready** security and scalability.
+- **Visual builder interface** to quickly get started and iterate .
+- **Source code access** lets you customize any component using Python.
+- **Interactive playground** to immediately test and refine your flows with step-by-step control.
+- **Multi-agent orchestration** with conversation management and retrieval.
+- **Deploy as an API** or export as JSON for Python apps.
+- **Observability** with LangSmith, LangFuse and other integrations.
+- **Enterprise-ready** security and scalability.
## ⚡️ Quickstart
-Langflow works with Python 3.10 to 3.13.
+Langflow requires [Python 3.10 to 3.13](https://www.python.org/downloads/release/python-3100/) and [uv](https://docs.astral.sh/uv/getting-started/installation/).
-Install with uv **(recommended)**
+1. To install Langflow, run:
```shell
uv pip install langflow
```
-Install with pip
+2. To run Langflow, run:
```shell
-pip install langflow
+uv run langflow run
```
+3. Go to the default Langflow URL at `http://127.0.0.1:7860`.
+
+For more information about installing Langflow, including Docker and Desktop options, see [Install Langflow](https://docs.langflow.org/get-started-installation).
+
## 📦 Deployment
-### Self-managed
-
-Langflow is completely open source and you can deploy it to all major deployment clouds. Follow this [guide](https://docs.langflow.org/deployment-docker) to learn how to use Docker to deploy Langflow.
-
-### Fully-managed by DataStax
-
-DataStax Langflow is a full-managed environment with zero setup. Developers can [sign up for a free account](https://astra.datastax.com/signup?type=langflow) to get started.
+Langflow is completely open source and you can deploy it to all major deployment clouds. To learn how to use Docker to deploy Langflow, see the [Docker deployment guide](https://docs.langflow.org/deployment-docker).
## ⭐ Stay up-to-date
diff --git a/docs/docs/Get-Started/get-started-installation.md b/docs/docs/Get-Started/get-started-installation.md
index 8232f8b33..9917f2190 100644
--- a/docs/docs/Get-Started/get-started-installation.md
+++ b/docs/docs/Get-Started/get-started-installation.md
@@ -6,179 +6,207 @@ slug: /get-started-installation
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
-Langflow can be installed in three ways:
+Langflow can be installed in multiple ways:
-* As a [Python package](#install-and-run-langflow-oss) with Langflow OSS
-* As a [standalone desktop application](#install-and-run-langflow-desktop) with Langflow Desktop
-* As a [cloud-hosted service](#datastax-langflow) with DataStax Langflow
+* **Langflow Desktop (Recommended)**: Download and install the [standalone desktop application](#install-and-run-langflow-desktop) for the easiest setup experience.
-## Install and run Langflow OSS
+* **Docker**: Pull and run the [Docker image](#install-and-run-langflow-docker) to start a Langflow container.
-Before you install and run Langflow OSS, be sure you have the following items.
+* **Python package**: Install the [Langflow OSS Python package](#install-and-run-langflow-oss).
-- [Python 3.10 to 3.13](https://www.python.org/downloads/release/python-3100/)
-- [uv](https://docs.astral.sh/uv/getting-started/installation/) or [pip](https://pypi.org/project/pip/)
-- A virtual environment created with [uv](https://docs.astral.sh/uv/pip/environments) or [venv](https://docs.python.org/3/library/venv.html)
-- A dual-core CPU and at least 2 GB of RAM. More intensive use requires a multi-core CPU and at least 4 GB of RAM.
+## Install and run Langflow Desktop
-Install and run Langflow OSS with [uv (recommended)](https://docs.astral.sh/uv/getting-started/installation/) or [pip](https://pypi.org/project/pip/).
+**Langflow Desktop** is a desktop version of Langflow that includes all the features of open source Langflow, with an additional [version management](#manage-your-langflow-version-in-langflow-desktop) feature for managing your Langflow version.
-1. To install Langflow, use one of the following commands:
+
+
-
-
+ 1. Navigate to [Langflow Desktop](https://www.langflow.org/desktop).
+ 2. Click **Download Langflow**, enter your contact information, and then click **Download**.
+ 3. Mount and install the Langflow application.
+ 4. When the installation completes, open the Langflow application.
-```bash
-uv pip install langflow
-```
+ After confirming that Langflow is running, create your first flow with the [Quickstart](/get-started-quickstart).
-
-
+
+
+ :::important
+ Windows installations of Langflow Desktop require a C++ compiler, such as [Visual Studio](https://visualstudio.microsoft.com/downloads/), that may not be present on your system. If you receive a `C++ Build Tools Required!` error, follow the on-screen prompt to install Microsoft C++ Build Tools, or visit the Visual Studio download link above.
+ :::
-```bash
-pip install langflow
-```
+ 1. Navigate to [Langflow Desktop](https://www.langflow.org/desktop).
+ 2. Click **Download Langflow**, enter your contact information, and then click **Download**.
+ 3. Open the **File Explorer**, and then navigate to **Downloads**.
+ 4. Double-click the downloaded `.msi` file, and then use the install wizard to install Langflow Desktop.
+ 6. When the installation completes, open the Langflow application.
+
+ After confirming that Langflow is running, create your first flow with the [Quickstart](/get-started-quickstart).
+
+
-
-2. To run Langflow, use one of the following commands:
+### Manage your version of Langflow Desktop
-
-
+When a new version of Langflow is available, Langflow Desktop displays an upgrade message.
-```bash
-uv run langflow run
+To manage your version of Langflow Desktop, follow these steps:
+
+ 1. In Langflow Desktop, click your profile image, and then select **Version Management**.
+ The **Version Management** pane lists your active Langflow version first, followed by other available versions.
+ The **latest** version is always highlighted.
+ 2. To change your Langflow version, select another version.
+ A confirmation pane containing the selected version's changelog appears.
+ 3. To apply the change, click **Confirm**.
+ Langflow desktop restarts to install and activate the new version.
+
+## Install and run Langflow with Docker {#install-and-run-langflow-docker}
+
+You can use the [Langflow Docker image](https://hub.docker.com/r/langflowai/langflow) to run Langflow in an isolated environment.
+Running applications in [Docker](https://docs.docker.com/) containers ensures consistent behavior across different systems and eliminates dependency conflicts.
+
+1. Install and start [Docker](https://docs.docker.com/).
+2. Pull the latest [Langflow Docker image](https://hub.docker.com/r/langflowai/langflow) and start it:
+
+ ```bash
+ docker run -p 7860:7860 langflowai/langflow:latest
+ ```
+
+3. To access Langflow, navigate to `http://localhost:7860/`.
+
+For more information, see [Deploy Langflow on Docker](/deployment-docker).
+
+## Install and run the Langflow OSS Python package
+
+To install and run Langflow OSS, you need the following:
+
+- [Python 3.10 to 3.13](https://www.python.org/downloads/release/python-3100/) for macOS/Linux, and Python 3.10 to 3.12 for Windows
+- [uv](https://docs.astral.sh/uv/getting-started/installation/)
+- At minimum, a dual-core CPU and 2 GB RAM, but a multi-core CPU and at least 4 GB RAM are recommended
+
+1. Create a virtual environment with [uv](https://docs.astral.sh/uv/pip/environments).
+
+
+Need help with virtual environments?
+
+Virtual environments ensure Langflow is installed in an isolated, fresh environment.
+To create a new virtual environment, do the following.
+
+
+
+ 1. Navigate to where you want your virtual environment to be created, and create it with `uv`.
+Replace `VENV_NAME` with your preferred name for your virtual environment.
```
-
-
-
-
-```bash
-python -m langflow run
+uv venv VENV_NAME
```
+2. Start the virtual environment.
+```
+source VENV_NAME/bin/activate
+```
+Your shell's prompt changes to display that you're currently working in a virtual environment.
+```
+(VENV_NAME) ➜ langflow git:(main) ✗
+```
+3. To deactivate the virtual environment and return to your regular shell, type `deactivate`.
+ When activated, the virtual environment temporarily modifies your PATH variable to prioritize packages installed within the virtual environment, so always deactivate it when you're done to avoid conflicts with other projects.
+To delete the virtual environment, type `rm -rf VENV_NAME`.
+
+
+1. Navigate to where you want your virtual environment to be created, and create it with `uv`.
+Replace `VENV_NAME` with your preferred name for your virtual environment.
+```
+uv venv VENV_NAME
+```
+2. Start the virtual environment.
+```shell
+VENV_NAME\Scripts\activate
+```
+Your shell's prompt changes to display that you're currently working in a virtual environment.
+```
+(VENV_NAME) PS C:/users/username/langflow-dir>
+```
+3. To deactivate the virtual environment and return to your regular shell, type `deactivate`.
+ When activated, the virtual environment temporarily modifies your PATH variable to prioritize packages installed within the virtual environment, so always deactivate it when you're done to avoid conflicts with other projects.
+To delete the virtual environment, type `Remove-Item VENV_NAME`.
+
+
-
-
+
-3. To confirm that a local Langflow instance starts, go to the default Langflow URL at `http://localhost:7860`.
+2. To install Langflow, run the following command.
+ ```bash
+ uv pip install langflow
+ ```
+
+3. After installation, start Langflow:
+ ```bash
+ uv run langflow run
+ ```
+
+4. To confirm that a local Langflow instance is running, navigate to the default Langflow URL `http://127.0.0.1:7860`.
+It can take a few minutes for Langflow to start.
After confirming that Langflow is running, create your first flow with the [Quickstart](/get-started-quickstart).
### Manage Langflow OSS versions
-To upgrade Langflow to the latest version, use one of the following commands:
+To manage your Langflow version, use the following commands.
-
-
+
+Manage Langflow OSS versions
+
+To upgrade Langflow to the latest version:
```bash
uv pip install langflow -U
```
-
-
-
-```bash
-pip install langflow -U
-```
-
-
-
-
-To install a specific version of the Langflow package, add the required version to the command.
-
-
+To install a specific version of the Langflow package, add the required version to the command:
```bash
uv pip install langflow==1.3.2
```
-
-
-
-```bash
-pip install langflow==1.3.2
-```
-
-
-
-
-To reinstall Langflow and all of its dependencies, add the `--force-reinstall` flag to the command.
-
-
+To reinstall Langflow and all of its dependencies, add the `--force-reinstall` flag to the command:
```bash
uv pip install langflow --force-reinstall
```
-
-
+
-```bash
-pip install langflow --force-reinstall
-```
-
-
-
-### Install optional dependencies for Langflow OSS
+### Manage Langflow OSS dependencies
Langflow OSS provides optional dependency groups that extend its functionality.
These dependencies are listed in the [pyproject.toml](https://github.com/langflow-ai/langflow/blob/main/pyproject.toml#L191) file under `[project.optional-dependencies]`.
-Install dependency groups using pip's `[extras]` syntax. For example, to install Langflow with the `postgresql` dependency group, enter one of the following commands:
+
+Install dependency groups
-
-
+Install dependency groups using pip's `[extras]` syntax. For example, to install Langflow with the `postgresql` dependency group, enter the following command:
```bash
uv pip install "langflow[postgresql]"
```
-
-
-
-```bash
-pip install "langflow[postgresql]"
-```
-
-
-
-
-To install multiple extras, enter one of the following commands:
-
-
-
+To install multiple extras, enter the following command:
```bash
uv pip install "langflow[deploy,local,postgresql]"
```
-
-
-
-```bash
-pip install "langflow[deploy,local,postgresql]"
-```
-
-
-
-
To add your own custom dependencies, see [Install custom dependencies](/install-custom-dependencies).
-### Stop Langflow OSS
-
-To stop Langflow, in the terminal where it's running, enter `Ctrl+C`.
-
-To deactivate your virtual environment, enter `deactivate`.
+
### Common OSS installation issues
This is a list of possible issues that you may encounter when installing and running Langflow.
-#### No `langflow.__main__` module
+
+No langflow.__main__ module
When you try to run Langflow with the command `langflow run`, you encounter the following error:
@@ -190,7 +218,10 @@ When you try to run Langflow with the command `langflow run`, you encounter the
2. If that doesn't work, reinstall the latest Langflow version with `uv pip install langflow -U`.
3. If that doesn't work, reinstall Langflow and its dependencies with `uv pip install langflow --pre -U --force-reinstall`.
-#### Langflow runTraceback
+
+
+
+Langflow runTraceback
When you try to run Langflow using the command `langflow run`, you encounter the following error:
@@ -203,7 +234,10 @@ There are two possible reasons for this error:
1. You've installed Langflow using `pip install langflow` but you already had a previous version of Langflow installed in your system. In this case, you might be running the wrong executable. To solve this issue, run the correct executable by running `python -m langflow run` instead of `langflow run`. If that doesn't work, try uninstalling and reinstalling Langflow with `uv pip install langflow --pre -U`.
2. Some version conflicts might have occurred during the installation process. Run `python -m pip install langflow --pre -U --force-reinstall` to reinstall Langflow and its dependencies.
-#### Something went wrong running migrations
+
+
+
+Something went wrong running migrations
```bash
> Something went wrong running migrations. Please, run 'langflow migration --fix'
@@ -220,7 +254,10 @@ This error can occur during Langflow upgrades when the new version can't overrid
If you wish to retain your files, back them up before clearing the folder.
-#### Langflow installation freezes at pip dependency resolution
+
+
+
+Langflow installation freezes at pip dependency resolution
Installing Langflow with `pip install langflow` slowly fails with this error message:
@@ -240,7 +277,10 @@ To run Langflow with uv:
uv run langflow run
```
-#### Failed to build required package
+
+
+
+Failed to build required package
When you try to install Langflow on Linux, installation fails because of outdated or missing packages.
@@ -264,44 +304,11 @@ sudo apt-get install build-essential python3-dev
sudo apt-get install gcc
```
-## Install and run Langflow Desktop
+
-:::important
-Langflow Desktop is in **Alpha**.
-Development is ongoing, and the features and functionality are subject to change.
-:::
+
+Installation failure from webrtcvad package
-**Langflow Desktop** is a desktop version of Langflow that includes all the features of open source Langflow, with an additional [version management](#manage-your-langflow-version-in-langflow-desktop) feature for managing your Langflow version.
+If you experience an error from the `webrtcvad` package, run `uv pip install webrtcvad-wheels` in the virtual environment, and then try installing again.
-:::important
-Langflow Desktop is available only for macOS.
-:::
-
-To install Langflow Desktop, follow these steps:
-
-1. Navigate to [Langflow Desktop](https://www.langflow.org/desktop).
-2. Enter your **Name**, **Email address**, and **Company**, and then click **Download**.
-3. Open the **Finder**, and then navigate to **Downloads**.
-4. Double-click the downloaded `*.dmg` file.
-5. To install Langflow Desktop, drag and drop the application icon to the **Applications** folder.
-6. When the installation completes, open the Langflow application.
-
-The application checks [uv](https://docs.astral.sh/uv/concepts/tools/), your local environment, and the Langflow version, and then starts.
-
-### Manage your Langflow version in Langflow Desktop
-
-When a new version of Langflow is available, Langflow Desktop displays an upgrade message.
-
-To manage your Langflow version in Langflow Desktop, follow these steps:
-
-1. To access Langflow Desktop's **Version Management** pane, click your **Profile Image**, and then select **Version Management**.
-Langflow Desktop's current version is displayed, with other version options listed after it.
-The **latest** version is always highlighted.
-2. To change your Langflow version, select another version.
-A confirmation pane containing the selected version's changelog appears.
-3. To change to the selected version, click **Confirm**.
-The application restarts with the new version installed.
-
-## DataStax Langflow {#datastax-langflow}
-
-**DataStax Langflow** is a hosted version of Langflow integrated with [Astra DB](https://www.datastax.com/products/datastax-astra). Be up and running in minutes with no installation or setup required. [Sign up for free](https://astra.datastax.com/signup?type=langflow).
+
\ No newline at end of file