Airflow 설치부터 DAG 확인까지 해보기! (Airflow 3.0 기준)

Airflow 공식 문서에는 Python 3.9 이상, 그리고 pip 또는 uv를 통한 설치 방식을 권장하고 있습니다. 이 글에서는 Docker 없이, uv를 사용해 간단하고 빠르게 Airflow를 설치하고 실행하는 방법으로 정리했습니다.

✅ 참고: Poetry나 pip-tools로도 설치가 가능하지만, Airflow는 constraints.txt를 기반으로 의존성을 관리하기 때문에 공식적으로는 pip 또는 uv 방식만 지원됩니다.

---

🛠 1. Airflow 설치해보기

MacOS / Linux 버전

Python 버전 확인

python --version

AIRFLOW_HOME 설정 (선택)

export AIRFLOW_HOME=~/my_airflow

uv 설치

• uv는 빠르고 현대적인 Python 환경/패키지 관리 도구

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

uv --version

Airflow 설치

uv venv  # 가상환경 생성
source .venv/bin/activate  # 가상환경 활성화

# Airflow 버전 지정 (예: 3.0.2)
AIRFLOW_VERSION=3.0.2

# 현재 파이썬 버전 추출 (예: 3.11)
PYTHON_VERSION=$(python -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")

# 제약 조건 파일 URL 지정
CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"

# Airflow 설치
uv pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"

Airflow Standalone 실행

• Airflow 2.5 이상부터는 모든 구성요소(Webserver, Scheduler 등)를 한 번에 실행할 수 있는 standalone 명령어가 생김

airflow standalone

🔹 실행 시 다음 작업이 자동으로 수행됨

• DB 초기화
• 관리자 계정 생성
• 웹 서버, 스케줄러 실행

Windows 버전 (with Docker)

• 공식적으로는 Windows를 지원하지 않기 때문에 WSL 또는 Docker 환경에서 진행해야 함

Docker 및 Docker Compose 설치 확인

• Docker Desktop 설치 시 Docker Compose도 함께 설치됨

# powershell이나 CMD에서 진행
docker -v
docker-compose -v

작업 폴더 생성 및 이동

• 폴더명을 자유롭게 지정해서 생성하고 이동

# powershell이나 CMD에서 진행
mkdir airflow-docker
cd airflow-docker

docker-compose.yaml 파일 다운로드

• 윈도우에서 curl 명령어가 안될 수 있으므로, 공식 사이트에서 파일을 다운로드하여 생성한 폴더에 저장
• 내가 다운로드한 파일 : https://airflow.apache.org/docs/apache-airflow/3.0.2/docker-compose.yaml
  • 마우스 우클릭 -> ‘다른 이름으로 링크 저장’ -> docker-compose.yaml로 저장

.env파일 생성

• 메모장같은 텍스트 편집기로 .env파일을 생성했던 폴더에 만들어서 아래 내용 입력

AIRFLOW_UID=50000

필수 디렉토리 생성

# powershell이나 CMD에서 진행
mkdir dags,logs,plugins,config

Airflow 환경 초기화

# powershell이나 CMD에서 진행
docker-compose up airflow-init

Airflow 실행

# powershell이나 CMD에서 진행
docker-compose up # 모든 서비스가 실행

# 백그라운드에서 실행
docker-compose up -d

컨테이너 상태 확인

• 실행중인 컨테이너 목록이 출력됨

docker ps

Web UI 접속

• 접속 주소: http://localhost:8080 🔹 로그인 화면

• 기본 로그인
  • ID: airflow
  • PW: airflow
• MacOS/Linux에서 standalone으로 실행시킨 경우
  • 로그에 비밀번호가 나와있음.

  # 이런 식으로 나와있음
  standalone | Starting Airflow Standalone
  standalone | Password for the admin user has been previously generated in /Users/haebin/my_airflow/simple_auth_manager_passwords.json.generated. Not echoing it here.
  
  # 혹은 이런식으로 나와있음
  standalone | Starting Airflow Standalone
  Simple auth manager | Password for user 'admin': [비밀번호]
  

🔹 로그인 후 메인 화면

🔎 2. Airflow 기본 설정

🔹 예제 DAG 숨기기

• Airflow Web UI에서 DAG 목록을 보면 내가 생성하지 않았던 예제 DAG들도 존재
• 예제 DAG를 안보이게 하고 싶을 때는 폴더에 있는 docker-compose.yaml에서 아래 옵션을 추가하거나 true로 되어있던 것을 false로 변경
  • AIRFLOW__CORE__LOAD_EXAMPLES: 'false'
    
• MacOS/Linux의 경우 airflow.cfg 파일이 있을텐데 그 파일을 열어서 load_examples를 False로 설정하면 됨
  • load_examples = False
  • 설정하고 다시 airflow standalone 실행
    • 그래도 예시 DAG가 나온다면 airflow db reset해야함
      • DB에 메타데이터가 남아있기 때문

🔹 DAG 폴더 수정하기

• MacOS/Linux의 경우 airflow.cfg 파일에 dags_folder변수가 있음
  • 내가 원하는 경로로 지정해주고, 그 폴더 경로에 dag 파일들을 넣으면 됨.
  • ex) dags_folder = /Users/user/airflow/dags

🔹 설정 반영 (Docker)

docker compose down -v  # 볼륨까지 초기화 (예제 DAG 제거)
docker compose up -d

🔹 로그가 보이지 않는 오류 해결 (Airflow 3.0 이상)

• Airflow Web UI에서 DAG을 실행한 뒤 Task를 클릭했을 때 로그가 아래처럼 보이지 않는 문제가 발생할 수 있음.

  Could not read served logs: Invalid URL 'http://:8793/...': No host supplied

• 이는 Airflow가 로그를 웹에서 보여주기 위해 URL을 생성할 때, 호스트 정보가 누락되어 잘못된 URL을 생성하기 때문

Airflow 3.0부터는 로그 URL 생성을 위한 AIRFLOW__LOGGING__HOSTNAME_CALLABLE 환경변수를 직접 지정해줘야 함

✅ 해결 방법

👉 로컬(macOS / Linux) 환경 - export AIRFLOW__LOGGING__HOSTNAME_CALLABLE=socket:gethostname

👉 Windows PowerShell 환경 - $env:AIRFLOW__LOGGING__HOSTNAME_CALLABLE = "socket:gethostname"

👉 Docker Compose 환경 - docker-compose.yml 파일의 airflow-webserver 서비스에 아래 항목을 추가

```yaml
services:
  airflow-webserver:
    environment:
      - AIRFLOW__LOGGING__HOSTNAME_CALLABLE: socket:gethostname
```

🔄 설정 후에는 compose down과 up으로 Airflow를 재시작해야 변경 내용이 반영

📁 3. DAG 생성 후 실행하기

🧱 DAG 파일 만들기

• Airflow는 dags_folder에 있는 .py 파일을 자동으로 감지하여 DAG으로 등록
  • 앞의 내용으로 설치를 했던 Windows 사용자들은 dags폴더에 있는 .py파일을 자동으로 감지

1. 설정한 dags 디렉토리로 이동
2. 아래와 같은 example_dag.py파일을 하나 생성하기

from airflow import DAG
from airflow.operators.bash import BashOperator
from datetime import datetime

# DAG 정의
with DAG(
    dag_id="example_dag",  #dag id 설정. 같은 id의 dag가 있으면 안됨
    start_date=datetime(2025, 7, 1),  # 시작 날짜 설정
    schedule="@once",  # 수동 또는 최초 한 번만 실행
    catchup=False,  # start_date부터 현재까지 과거 날짜를 한꺼번에 실행할지 여부. False면 지금 시점 이후만 실행
    description="간단한 DAG 예제"
) as dag:

    task1 = BashOperator(
        task_id="start_task",
        bash_command="echo '🚀 Start task running!'"
    )

    task2 = BashOperator(
        task_id="end_task",
        bash_command="echo '✅ End task finished!'"
    )

    # 의존성 설정: task1이 먼저, task2가 그다음
    task1 >> task2

🔹 dag 생성 후 Web UI

🚀 DAG 파일 실행하기

1️⃣ DAG 목록에서 실행할 DAG 찾기

• 실행하고 싶은 DAG를 목록에서 찾기
• 오른쪽 토글 버튼 클릭해서 DAG을 활성화(ON) 해야 실행 가능

2️⃣ DAG 실행 (Trigger)

• DAG 이름 클릭 → DAG 상세 페이지로 이동

• 상단 우측 💥 Trigger 버튼 클릭

※ Airflow 3.0에서는 ▶ 아이콘 대신 Trigger 버튼이 명시적으로 표시됨

3️⃣ 실행 상태 확인

• Grid View (기존 Tree View) → DAG 실행 이력과 Task 상태 확인 가능
  → 초록색이면 성공, 빨간색은 실패, 회색은 미실행

• Graph View → Task 간 연결 구조를 시각적으로 확인 가능
  

4️⃣ 🧾 Task 로그 확인

• Grid 또는 Graph에서 Task 아이콘 클릭 → 오른쪽 사이드바 열림 -> “Task Instances” 탭으로 이동
• “Logs” 버튼 클릭

• BashOperator일 경우 다음과 같은 로그가 표시됨:

  Log message source details: sources=["/opt/airflow/logs/dag_id=example_dag/run_id=manual__2025-07-03T05:45:24.483154+00:00/task_id=start_task/attempt=1.log"]
  ...
  [2025-07-03, 14:45:25] INFO - 🚀 Start task running!:
  ...
  

Data-Engineering 카테고리 내 다른 글 보러가기