03a_contributors_quick_start_beginners.rst

Your First Airflow Pull Request — 15-Minute Guide

On this page

• Purpose
• Prerequisites
• Option A – Breeze on Your Laptop
• Option B – One-Click GitHub Codespaces
• Review & Merge
• Next Steps

Purpose

This page walks new contributors through opening their first Apache Airflow pull request (PR) in about five minutes. We present one local option (Breeze) and one fully-hosted option (GitHub Codespaces). Everything else lives in the advanced guides.

Prerequisites

• GitHub account
• Fork apache/airflow
• Basic Git (only required for the Breeze path below)

For Breeze (local development):

• Docker Desktop
• Podman, a drop-in, license-friendly replacement for Docker Desktop
• Docker Compose
• uv, which is a fast, reliable package manager that you'll use to install other developer tools to make contributing to Airflow easier.

curl -LsSf https://astral.sh/uv/install.sh | sh

• Prek, which runs Airflow's required code-quality checks (formatting, linting, and bug-spotting) before you commit, helping save contributors and committers time during the pull request process.

uv tool install prek
prek install -f
prek install -f --hook-type pre-push

• 4GB RAM, 40GB disk space, and at least 2 CPU cores

Note

Docker or Podman installation varies by OS. See the full guide for Ubuntu, macOS, and Windows instructions.

Option A – Breeze on Your Laptop

1. Clone your fork and install Breeze

git clone https://github.com/<you>/airflow.git
cd airflow
uv tool install -e ./dev/breeze

2. Setup your idea workspace to detect project src/ and tests/ folders as source roots.

# For IntelliJ IDEA and PyCharm
uv run dev/ide_setup/setup_idea.py

# For VS Code
uv run dev/ide_setup/setup_vscode.py

3. Start the development container (first run builds the image)

breeze start-airflow

The command starts a shell and launches multiple terminals using tmux and launches all Airflow necessary components in those terminals. To know more about tmux commands, check out this cheat sheet: https://tmuxcheatsheet.com/. Now You can also access Airflow UI on your local machine at |http://localhost:28080| with user name admin and password admin. To exit breeze, type stop_airflow in any of the tmux panes and hit Enter

Working with DAGs in Breeze:

• Adding your own DAGs: Place your DAG files in the /files/dags/ directory in your local Airflow repository. This directory is automatically mounted into the Breeze container and your DAGs will be visible in the Airflow UI.
• Loading example DAGs: Use the --load-example-dags flag to load all example DAGs from the repository:

breeze start-airflow --load-example-dags

This flag enables configuration to load example DAGs when starting Airflow, which is useful for exploring Airflow's capabilities and testing.

4. Make a tiny change – e.g. fix a typo in docs
5. Run local checks

prek --all-files

6. Commit & push

git checkout -b docs-typo
git commit -am "fix typo in README"
git push -u origin docs-typo

7. Open the PR – GitHub shows a "Compare & pull request" button.

Syncing your branch

git fetch upstream && git rebase upstream/main && git push --force-with-lease

Option B – One-Click GitHub Codespaces

1. On your fork, click Code → Codespaces → New codespace.
2. Wait for the VS Code web IDE to appear. A terminal opens automatically.
3. Install Docker Buildx and Docker Compose (required for Breeze)

mkdir -p ~/.docker/cli-plugins

# Install Docker Buildx
BUILDX_VERSION=v0.16.2
curl -SL "https://github.com/docker/buildx/releases/download/${BUILDX_VERSION}/buildx-${BUILDX_VERSION}.linux-amd64" -o ~/.docker/cli-plugins/docker-buildx
chmod +x ~/.docker/cli-plugins/docker-buildx
docker buildx version

# Install Docker Compose v2
curl -SL "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)" -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose
docker compose version

4. Install Breeze and start the development container

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install prek
prek install -f
prek install -f --hook-type pre-push # for running mypy checks when pushing to repo
uv tool install -e ./dev/breeze
uv run dev/ide_setup/setup_vscode.py
breeze start-airflow

5. Edit a file in the editor, save, and commit via the Source Control sidebar. Push when prompted.
6. Press Create pull request when GitHub offers.

Review & Merge

Respond to reviewer comments, push updates (same commands as above). Once CI is green and reviews are ✅, a committer will merge. 🎉

Next Steps

• Need a full development environment? See the Development Environments Guide.
• Learn about our contribution workflow? Checkout the Contribution Workflow Guide.