Airflow 로컬 IDE 디버깅 환경 구축

기존에는 Docker Compose만을 이용하여 로컬에서 Airflow를 실행하고 테스트했습니다.
통합 테스트 관점에서는 충분했지만, 실제 로직을 추적하며 디버깅하기에는 불편함이 있었습니다.

 

특히,

• breakpoint 사용 불가
• step-through 디버깅 불가
• 태스크 단위 검증의 번거로움

이 문제로 인해 IDE 기반 디버깅 환경의 필요성을 느끼게 되었습니다.

그래서 다음과 같이 개발 환경을 이원화하였습니다.

 

로컬 개발 환경 전략에 대해서 설명 드리고, Airflow Debug 환경 구축 방법에 대해 공유하고자 합니다.

Airflow 로컬 실행 환경 전략

1. Airflow Debug Test

• 로컬 개발/디버깅 용
• IDE 디버깅(PyCharm) 사용
• 로컬 Python venv (uv 기반)의 airflow 사용
• dags test 명령어로 Scheduler 없이 DAG 단일 실행

Docker Interpreter를 연결하면 컨테이너 환경과 동일하게 디버깅할 수 있으나, 이는 PyCharm Pro에서만 가능합니다. 추후 가이드 공유 예정입니다.

 

2. Docker Airflow 

• 로컬 통합/환경 검증 테스트 용
• docker container 내부 airflow 실행
• Scheduler, Worker 포함 전체 동작 확인

Airflow Debug 셋팅

1. DB Migration (초기 1회)

로컬 디버깅 전용 Airflow 메타 DB를 초기화합니다.

 

각자 개발 환경 경로에 맞게 변경 후 실행하면 됩니다. 

source .venv/bin/activate
export AIRFLOW_HOME=$(pwd)/.airflow-debug-config
airflow db migrate

 

성공하면 .airflow-debug-config/airflow.db, airflow.cfg 파일이 생성됩니다.

(⚠️ 로컬 디버깅 용 airflow meta data 및 설정 파일이므로, 배포 안되게 주의)

2. IDE Run Configuration

• 셋팅 기준 버전
  • PyCharm 2025.1.3.1
  • Airflow 3.3
    • 현 프로젝트는 uv 가상환경으로 관리 중.
    • 각자 프로젝트 가상환경에 설치된 airflow 사용됨.
• 실행 유형: Module 실행
• 로컬 PC 절대 경로로 입력하기

설정값	값
실행 타입	Module
Module name	airflow
Parameters	dags test {{실행할 dag_id}} {{excution_date}} # dags test test_dags_1 2026-02-20
Python Interpreter	프로젝트 설정 가상환경 # 각자 로컬에 Airflow 가 설치되어 있는 Python 가상환경을 설정하면 됨 `.venv/bin.python3.12`
작업 디렉터리	{{HOME 경로}} # dags 바로 상위 디렉토리
Environment Variables	AIRFLOW__CORE__DAGS_FOLDER={{HOME 경로}}/dags;AIRFLOW_HOME={{HOME 경로}}/.airflow-debug-config;PYTHONUNBUFFERED=1
체크 옵션	시작 시 실행/디버그 도구 창 열기 콘텐츠 루트를 PYTHONPATH에 추가 소스 루트를 PYTHONPATH에 추가

 

해당 셋팅을 통해서 IDE 에서 제어 가능한 상태에서

아래 airflow Command Line Interface (CLI) 이 실행되어, 디버깅이 가능해집니다.

• dags test

airflow dags test [dag_id] [execution_date]

• task test

airflow tasks test [dag_id] [task_id] [execution_date]

테스트 원하는 dag , task 에 맞춰서 실행 Parameters을 셋팅하시면 됩니다.

 

---

 

로컬 환경을 역할 기반으로 분리함으로써, 개발 단계별 목적에 맞게 개발 및 검증이 가능해졌습니다.

 

1. 로컬 venv Airflow → 로직 개발 및 디버깅
2. Docker Compose → 로컬에서 통합 및 환경 검증

3. 배포

 

향후 확장 계획

기존 통합 테스트용 Docker Compose 환경에서 직접 IDE 디버깅까지 가능하면 더 이상적일 것으로 생각합니다.
다만, 이는 PyCharm Professional에서만 Docker Interpreter 연결이 가능합니다.

 

현재는 Community 버전을 사용 중이므로 적용하지 않았으며,
추후 PyCharm Pro 환경에서 검증 후 별도 가이드를 공유할 예정입니다.