Confused at the mixing of uv and pip/venv instructions in Quick Start guide

[Stevoisiak]

In the Quick Start guide for Airflow, I'm confused at how the steps for installation via uv and pip/venv are mixed together.

Step 2 says to install airflow in a virtual environment using uv instead of pip and venv. It then links instructions on how to install uv, but doesn't list the commands to run for installing Airflow with uv. Instead, the next listed commands are on how to install using pip and venv. But then, step 3 lists how to install Airflow using the constraints file using uv, which seems like a repeat of what step 2 already said to do.

When I try installing uv with curl -LsSf https://astral.sh/uv/install.sh | sh as instructed in step 2, then running the uv command to install airflow in step 3, I get an error Command 'python' not found. I believe the issue is that the Python installation step is bundled in with Step 2's code, but that code was explained as how to install with pip and venv, rather than being explained as required for uv installation.

What is the correct order of steps to follow when installing with uv?

[GiorgioRafael]

The guide is currently mixing two alternative paths. If you choose uv, you do not need to run the pip/venv block, but you do need to create a Python environment before evaluating the line that calls python -c.

A consistent uv-only order is:

# Airflow requires Linux/WSL2 on Windows
export AIRFLOW_HOME=~/airflow
mkdir -p $AIRFLOW_HOME
cd $AIRFLOW_HOME

# Install uv using its official installation guide, then:
PYTHON_VERSION=3.12
AIRFLOW_VERSION=3.3.0

uv python install $PYTHON_VERSION
uv venv --python $PYTHON_VERSION airflow_venv
source airflow_venv/bin/activate

CONSTRAINT_URL=https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt
uv pip install apache-airflow==${AIRFLOW_VERSION} --constraint $CONSTRAINT_URL

airflow version
airflow standalone

The Command 'python' not found error occurs because installing the uv executable alone does not necessarily place an unversioned python executable on PATH, and the guide evaluates python -c ... before showing the missing uv venv step. Setting PYTHON_VERSION explicitly avoids that circular dependency; after activating airflow_venv, python will also resolve normally.

The current Airflow quick start lists Python 3.10–3.14 as supported: https://airflow.apache.org/docs/apache-airflow/stable/start.html. uv can install and manage the interpreter itself: https://docs.astral.sh/uv/guides/install-python/.

So your reading is correct: step 2 should show the uv python/uv venv setup, while the existing pip/venv block is a separate alternative.

[potiuk]

Improvements to the guide are most welcome