Airflow Setup in 2026: The Install That Never Comes Up

You followed the install guide, started the webserver, opened localhost:8080, and got a wall of 500 errors. Nothing in the guide warned you that one skipped command poisons everything after it.

That command is airflow db init. Without it the metadata tables don't exist, so every UI query fails. You'll learn the exact startup order that avoids this.

We'll pick an install path, run the 3.x quickstart, and tour the UI with purpose. Two minutes of order saves two hours of logs.

Choose an Install Path by Use Case

pip in a virtualenv is the learning path. It is fast, local, and disposable, perfect for reading the UI and running your first DAG. Its weakness is fidelity: your laptop is not production.

The official docker-compose stack is the team path. It adds Postgres, Redis, workers, and the webserver as services from one file. What runs on your machine mirrors what runs in staging.

Astro CLI wraps the compose pattern for Astronomer shops with project scaffolding. The Airflow 3 quickstart is the fastest hello-world when you want a running DAG in two minutes. Pick by destination, not by habit.

Official docs now bless pip or uv only — Poetry and pip-tools aren't supported for constraints. You'll target Python 3.10-3.14 on 3.2+. On Windows you must use WSL2 (wsl --install), then create the venv in Linux home, not the Windows mount.

Airflow 3 Quickstart: A 2-Minute Local Run

The 3.x quickstart stands up the full stack from the official compose file. An init service runs migrations, then the API server, scheduler, workers, and Postgres start in dependency order.

Give it two minutes, then open the UI and confirm the example DAGs parse. If the init step is skipped, you inherit the classic 500s failure from the incident above.

Keep this stack for the whole foundations phase. Every later article assumes Postgres-backed state, not the sqlite default.

Fastest hello today is pipx run apache-airflow standalone or uvx apache-airflow standalone: it inits SQLite, creates the admin user, and starts everything. The password lands in $AIRFLOW_HOME/simple_auth_manager_passwords.json.generated — cat that file if the terminal didn't print it. It's dev-only; prod splits into airflow api-server, airflow scheduler, airflow dag-processor, and airflow triggerer.

# fastest first run on Airflow 3.x (docs quickstart)
curl -LfO 'https://airflow.apache.org/docs/apache-airflow/stable/docker-compose.yaml'
mkdir -p ./dags ./logs ./plugins ./config
echo -e "AIRFLOW_UID=$(id -u)" > .env
docker compose up airflow-init
docker compose up -d
docker compose ps
# or bare-metal dev:
# pipx run apache-airflow standalone
# cat ~/airflow/simple_auth_manager_passwords.json.generated

Astro CLI for Astro-Style Dev

Astro CLI scaffolds an Astronomer-style project with dags, plugins, and tests in one layout. DataCamp-style courses use it because students get a runnable project without hand-writing compose files.

Daily commands mirror the compose flow: astro dev init once, astro dev start for the loop, astro dev pytest for task tests. Deploys push the same image your team reviews.

Use it when your destination is Astronomer or when you want opinionated structure. Otherwise the official compose file teaches the same lessons with fewer abstractions.

First UI Tour: Every Menu and What It Means

The DAGs list is mission control: pause toggles, recent run states, and schedule per DAG. Grid shows every task instance across runs as colored squares; Graph shows dependencies for one run. Learn both before touching code.

Docs renders each DAG's doc_md, Triggers covers manual and asset-driven launches, and Admin holds connections, variables, pools, and users. Most production incidents in this course are diagnosed from Grid plus a task log.

Click into a task instance early. Logs, XCom, and rendered templates live on its tabs. That panel is where failed runs explain themselves.

Learn the split: DAGs list is the fleet, Grid tracks states across runs, Graph shows one run's edges, Gantt shows durations, Docs renders doc_md, and Admin covers connections, variables, pools, and config. In 3.x the React UI adds DAG pinning and 17 languages, and Admin > Configuration shows the live airflow.cfg.

AIRFLOW_HOME and Where State Lives

AIRFLOW_HOME is the directory where config, logs, and the default sqlite file live. Every airflow command resolves it from the environment, falling back to ~/airflow. When two shells export different values, you run two installs wearing one name.

State splits follow. Connections created in the UI vanish, DAG lists disagree, and logs scatter. The fix is boring: export one AIRFLOW_HOME in your shell profile and never override it ad hoc.

Check with airflow info whenever something looks haunted. It prints the home, executor, and database URL that component actually uses.

Verify a Healthy Install

Healthy installs answer four commands cleanly. airflow db check proves the metadata DB is reachable. airflow info prints versions, paths, and executor. airflow dags list proves parsing works. airflow connections list proves credential storage is wired.

Run all four after every fresh setup and after every upgrade. They take seconds and catch the ordering, path, and constraint failures that otherwise surface as mysterious UI behavior.

Only then write your first DAG. A green baseline turns later failures into DAG bugs instead of install mysteries.

After airflow db migrate (replaces db init in 3.x), run airflow dags list, airflow tasks list tutorial, and airflow dags show tutorial to prove parsing. Then airflow tasks test example_bash_operator runme_0 2015-01-01 for one task and airflow dags test for a full local run with no DB state.

# prove the install is healthy before writing DAGs
export AIRFLOW_HOME=~/airflow
airflow db migrate
airflow db check
airflow info
airflow dags list | head -20
airflow connections list
cat ~/airflow/simple_auth_manager_passwords.json.generated