Apache Airflow 를 pip 로 설치할 때는 Airflow 가 제공하는 constraint 파일을 반드시 함께 써야 의존성 충돌 없이 설치된다. Airflow 3.x 최신 버전과, 레거시 DAG 호환을 위해 2.6.x 를 Windows PC 에 올리는 경우를 함께 정리한다. Airflow 는 Windows 네이티브 설치를 지원하지 않으므로 Windows 에서는 WSL2 위에 설치한다.
export AIRFLOW_HOME=~/airflow
python3 -m venv ~/airflow/.venv
source ~/airflow/.venv/bin/activate
pip install --upgrade pip
AIRFLOW_VERSION=3.3.1
PYTHON_VERSION="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"
pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
pip install "apache-airflow[celery,postgres]==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
airflow version
Debian/Ubuntu 는 PEP 668 때문에 시스템 Python 에 직접 설치하면 externally-managed-environment 로 막히므로 가상환경이 필수다. constraint URL 이 404 면 그 Airflow 버전이 해당 Python 버전을 지원하지 않는 것이다. Provider 를 따로 설치할 때는 constraint 를 쓰지 않으며, 코어 버전이 바뀌지 않도록 함께 고정한다.
pip install "apache-airflow==3.3.1" "apache-airflow-providers-google==17.0.0"
실행은 airflow standalone 이 DB 초기화·admin 계정 생성·전 컴포넌트 기동을 한 번에 한다. 3.x 는 admin 비밀번호가 $AIRFLOW_HOME/simple_auth_manager_passwords.json.generated 에 저장된다. 개별 기동 시 3.x 는 webserver 가 아니라 api-server 다.
airflow db migrate
airflow api-server --port 8080
airflow scheduler
airflow dag-processor
airflow triggerer
2.6.x 는 2.6.3 이 마지막 패치이고 Python 3.7~3.11 에서 테스트됐으며 Python 3.10 을 권장한다(2.6.1 constraint 에 3.10 의존성 충돌 이슈가 있었다). 2023년 릴리스라 보안 패치가 끊긴 버전이므로 로컬 개발 외 용도로 8080 포트를 외부에 노출하지 않는다.
wsl --install
재부팅 후 Ubuntu 터미널에서 진행한다. /mnt/c 같은 Windows 마운트 경로는 느리고 권한 문제가 있으므로 Linux 홈 디렉터리를 쓴다.
sudo apt update
sudo apt install -y python3.10 python3.10-venv python3-pip build-essential libffi-dev libssl-dev
mkdir -p ~/airflow && cd ~/airflow
python3.10 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
echo 'export AIRFLOW_HOME=~/airflow' >> ~/.bashrc
source ~/.bashrc
AIRFLOW_VERSION=2.6.3
PYTHON_VERSION="$(python --version | cut -d " " -f 2 | cut -d "." -f 1-2)"
CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"
pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
airflow version
2.x 는 db init 과 webserver 를 쓴다. 비밀번호는 --password 인자로 남기지 말고 프롬프트에서 입력한다.
airflow db init
airflow users create --username admin --firstname Admin --lastname User --role Admin --email admin@example.com
airflow webserver --port 8080
airflow scheduler
airflow standalone 은 admin 비밀번호를 $AIRFLOW_HOME/standalone_admin_password.txt 에 저장한다. WSL2 는 localhost 포트를 자동 포워딩하므로 Windows 브라우저에서 http://localhost:8080 으로 열린다. DAG 폴더 ~/airflow/dags 는 \\wsl$\Ubuntu\home\<user>\airflow\dags 로 접근하거나 VS Code WSL 확장을 쓴다.
| 증상 | 원인 / 해결 |
|---|---|
error: externally-managed-environment |
가상환경 미사용. venv 안에서 설치 |
ResolutionImpossible 의존성 충돌 |
--constraint 누락 또는 2.6.1 사용. 2.6.3 + 3.10 조합으로 재설치 |
| constraint URL 404 | 해당 Airflow 버전이 그 Python 버전 미지원. PYTHON_VERSION 을 직접 지정 |
ModuleNotFoundError: No module named 'termios' |
네이티브 Windows 에서 실행한 것. WSL 터미널에서 실행 |
| 빌드 중 컴파일 에러 | gcc, python3-dev, libpq-dev 등 OS 패키지 설치 |
| WSL 메모리 과다 | %UserProfile%\.wslconfig 의 [wsl2] memory=4GB |
standalone 과 SQLite + SequentialExecutor 는 개발 전용이다. 운영은 Postgres/MySQL + Celery 또는 Kubernetes Executor 로 전환한다.airflow.cfg 에 평문으로 두지 말고 AIRFLOW__DATABASE__SQL_ALCHEMY_CONN, AIRFLOW__CORE__FERNET_KEY 환경변수나 Secrets Backend 로 주입하며 airflow.cfg 는 형상관리에서 제외한다.uv 를 쓰면 같은 명령 앞에 uv 만 붙이면 되고 설치가 빠르다.