How to Install Apache Airflow 3.1.3 on WSL (Windows Subsystem for Linux)

What is Apache Airflow?

Apache Airflow is an open-source platform used to programmatically author, schedule, and monitor workflows. It's widely used in data engineering, MLOps, and backend automation pipelines. If you're building ETL pipelines, running scheduled tasks, or orchestrating complex workflows, Airflow is a tool you'll likely encounter.

Airflow 3 is a major upgrade from Airflow 2 — it introduces a new React-based UI, a dedicated API server (replacing the old webserver), improved task isolation via the Task SDK, and better scalability overall.

Prerequisites

Before we begin, make sure you have the following in place:

1. Windows Subsystem for Linux (WSL2) installed

You need WSL 2 with Ubuntu 24.04 (Noble) installed on your Windows machine. If you haven't set it up yet, open PowerShell as Administrator and run:

wsl --install

Restart your machine when prompted, then launch Ubuntu from the Start menu.

Important: Always work inside the Linux home directory (~), not a Windows-mounted path like /mnt/c/.... Performance and file permission issues can occur on mounted drives.

2. MobiXterm or Windows Terminal (optional but recommended)

Either gives you a better terminal experience for working inside WSL.

3. Basic familiarity with the Linux terminal

You don't need to be a Linux expert, but knowing how to navigate directories (cd, ls) and run commands will help.

Step 1: Update Your System

Open your WSL terminal and run:

sudo apt update && sudo apt upgrade -y

This ensures your package lists and installed packages are up to date.

Step 2: Install Python 3 and Check the Version

Ubuntu 24.04 ships with Python 3.12 by default. Verify it's available:

python3 --version

You should see something like Python 3.12.x. Airflow 3.1.3 supports Python 3.10, 3.11, and 3.12 — so you're good.

If Python isn't installed:

sudo apt install python3 python3-dev python3-pip python3-venv -y

Step 3: Set Your AIRFLOW_HOME (Important — Do This First)

Airflow needs a home directory to store its configuration, logs, and database. Set this before installing Airflow so it knows where to store everything:

export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home

To make this permanent so it survives terminal restarts:

echo 'export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home' >> ~/.bashrc
source ~/.bashrc

Why this matters: If you skip this step, Airflow defaults to ~/airflow and may pick up config files from a previous Airflow installation, causing unexpected warnings or errors.

Step 4: Create a Project Directory and Virtual Environment

Create a dedicated folder for your Airflow 3.1.3 installation:

mkdir ~/airflow-3.1.3
cd ~/airflow-3.1.3

Create a virtual environment inside it:

python3 -m venv env

Activate the virtual environment:

source env/bin/activate

Your terminal prompt should now show (env) at the beginning:

(env) user@DESKTOP-XXXX:~/airflow-3.1.3$

Step 5: Upgrade pip

Before installing Airflow, upgrade pip to the latest version:

pip install --upgrade pip

Step 6: Install Apache Airflow 3.1.3 with Constraints

Install Airflow using the official constraints file. This is critical — Airflow has many dependencies, and the constraints file ensures compatible versions are installed together without conflicts:

pip install "apache-airflow==3.1.3" \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

This may take several minutes. Once complete, verify the installation:

airflow version

You should see:

3.1.3

Step 7: Install the FAB Auth Manager Provider

In Airflow 3, user authentication is handled by a separate provider package. Install it now — without it, the API server will fail to start:

pip install apache-airflow-providers-fab \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

Note: The airflow users command is only available when the FAB (Flask AppBuilder) auth manager provider is installed. This is a key difference from Airflow 2 where user management was built into core.

Step 8: Initialize the Airflow Database

Airflow 3 uses db migrate instead of the old db init command. This creates the metadata database and applies all schema migrations:

airflow db migrate

Step 9: Create an Admin User

airflow users create \
  --username admin \
  --firstname YourFirstName \
  --lastname YourLastName \
  --role Admin \
  --email [email protected]

You will be prompted to set a password. Type it carefully — input is hidden (no asterisks shown) in the terminal. Confirm it when prompted.

Tip: Remember this password — there's no plain-text copy stored anywhere. If you forget it, reset it with airflow users reset-password --username admin.

Step 10: Start the Airflow API Server and Scheduler

Airflow 3 requires three processes running simultaneously — the API server, the scheduler, and optionally the dag-processor (for larger setups). Open separate WSL terminal tabs or windows for each.

Terminal 1 — Start the API server:

cd ~/airflow-3.1.3
source env/bin/activate
export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home
airflow api-server --port 8080

Terminal 2 — Start the scheduler:

cd ~/airflow-3.1.3
source env/bin/activate
export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home
airflow scheduler

Note: In Airflow 3, airflow webserver has been replaced by airflow api-server. This is one of the key architectural changes from Airflow 2.

When the API server starts successfully you will see:

INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

And when the scheduler starts you will see:

INFO:     Starting the scheduler
INFO:     Loaded executor: LocalExecutor

Step 11: Access the Airflow UI

Open your browser and navigate to:

http://localhost:8080

You will see the new Airflow 3 React-based login page. Enter the username and password you created in Step 9.

You should now be inside the Airflow 3 Dashboard — ready to create and manage your DAGs!

Quick Reference: Starting Airflow After a Reboot

Every time you restart your machine and want to use Airflow, run these commands in separate terminals:

# All terminals: navigate, activate venv, and set AIRFLOW_HOME
cd ~/airflow-3.1.3
source env/bin/activate
export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home

# Terminal 1
airflow api-server --port 8080

# Terminal 2
airflow scheduler

If you added AIRFLOW_HOME to your ~/.bashrc in Step 3, the export is automatic and you can skip that line.

Airflow 3 vs Airflow 2 — Key Differences

If you're familiar with Airflow 2, here's what changed:

Troubleshooting

airflow users command not found

Install the FAB provider:

pip install apache-airflow-providers-fab \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

Deprecation warnings about [webserver] settings

These occur when Airflow 3 picks up a config file from an old Airflow 2 installation. Make sure AIRFLOW_HOME points to a fresh directory and not ~/airflow (the Airflow 2 default).

No module named 'airflow.providers.fab' warning

The FAB provider isn't installed. See Step 7 above.

Forgot your admin password

Reset it without deleting the user:

airflow users reset-password --username admin

Port 8080 already in use

Either stop the other process using port 8080, or start the API server on a different port:

airflow api-server --port 8081

Summary of All Commands

# Set AIRFLOW_HOME (permanent)
echo 'export AIRFLOW_HOME=~/airflow-3.1.3/airflow_home' >> ~/.bashrc
source ~/.bashrc

# Create project directory and virtual environment
mkdir ~/airflow-3.1.3 && cd ~/airflow-3.1.3
python3 -m venv env
source env/bin/activate

# Install Airflow with constraints
pip install --upgrade pip
pip install "apache-airflow==3.1.3" \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

# Install FAB auth manager provider
pip install apache-airflow-providers-fab \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.1.3/constraints-3.12.txt"

# Verify
airflow version

# Initialize database
airflow db migrate

# Create admin user
airflow users create --username admin --firstname YourFirstName \
  --lastname YourLastName --role Admin --email [email protected]

# Start services (separate terminals)
airflow api-server --port 8080    # Terminal 1
airflow scheduler                  # Terminal 2

What's Next?

Now that Airflow 3.1.3 is running, here are some things to explore next:

• Write your first DAG — create a Python file in $AIRFLOW_HOME/dags/ to define a workflow
• Explore the new UI — Airflow 3 ships with a brand new React-based interface with improved DAG views
• Learn about Assets — Airflow 3 introduces Assets (formerly Datasets) for data-aware scheduling
• Set up PostgreSQL — replace SQLite with PostgreSQL as the Airflow metadata backend for production use
• Use the Task SDK — Airflow 3 ships with a standalone Task SDK for writing tasks in isolation

For the official Airflow 3 Quick Start guide, visit: https://airflow.apache.org/docs/apache-airflow/stable/start.html