PyPI에서 설치하기
PyPI에서 설치하기 (Installation from PyPI)
이 문서는 PyPI에 게시된 apache-airflow 패키지를 사용한 설치 방법을 설명해요. pipx/uv로 도구처럼 설치하거나, 환경에 재현 가능하게 설치하는 방법, constraints 파일의 역할까지 다룹니다.
출처: 문서
본문
이 페이지는 PyPI에 게시된 apache-airflow 패키지를 사용한 설치를 설명해요.
pipx 또는 uv로 도구로서 설치하기
로컬 개발·테스트 환경에서는 PyPI에서 직접 Apache Airflow를 설치하고 실행할 수 있어요.
pipx를 사용한다면 아래 명령으로 PyPI에서 직접 실행할 수 있어요:
pipx run "apache-airflow==3.3.2" standalone
Astral uv를 통해 PyPI에서 다음을 사용해 설치할 수 있어요:
uv tool install "apache-airflow==3.3.2"
추가로 빠르게 시작하려면 uvx 명령을 통한 단축키를 사용해 먼저 설치하지 않고 직접 실행할 수도 있어요:
uvx apache-airflow standalone
환경에 설치하기 (Installation in your environment)
현재 공식적으로 지원되는 설치 방법은 pip와 uv뿐이에요.
Note
poetry나 pip-tools 같은 다른 도구로 성공한 사례가 있긴 하지만, 특히 constraint vs requirements 관리 측면에서
pip와 같은 워크플로우를 공유하지는 않아요.Poetry나pip-tools로의 설치는 현재 지원되지 않아요. 그런 도구로 Airflow를 설치하려면 constraints를 사용해 도구가 요구하는 적절한 형식과 워크플로우로 변환해야 해요. Uv는uv pip로pip접근 방식을 따르므로 비슷하게 동작할 거예요.
PyPI에서 Airflow를 재현 가능한 방식으로 처음부터 설치하는 전형적인 명령은 다음과 같아요:
pip install "apache-airflow[celery]==3.3.2" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.3.2/constraints-3.10.txt"
보통 재현 가능한 설치 후에 다른 dependencies와 providers를 별도의 명령으로 추가할 수 있어요 — 이렇게 하면 constraints에 제한되지 않고 원하는 대로 dependencies를 업그레이드하거나 다운그레이드할 수 있어요. 이런 경우 좋은 관행은 파일에 이미 설치된 버전으로 apache-airflow를 고정(pin)해 pip가 우연히 업그레이드하거나 다운그레이드하지 않도록 하는 거예요.
pip install "apache-airflow==3.3.2" apache-airflow-providers-google==10.1.0
이것들은 예시일 뿐이며, 왜 이것들이 모범 사례인지에 대한 자세한 설명은 아래에서 계속 확인할 수 있어요.
Note
일반적으로 Python 커뮤니티는
virtualenv나venv도구로 만든 가상 환경에서 애플리케이션을 설치하는 관행을 확립했어요.uv나pipx를 사용해 애플리케이션 전용 가상 환경에 Airflow를 설치할 수도 있어요. 가상 환경 설치를 관리하는 데 사용할 수 있는 다른 도구도 있으며, 환경 관리 방식을 자유롭게 선택할 수 있어요. Airflow는 가상 환경에 관한 도구 선택에 제한이 없어요.가상 환경을 사용하지 않는 것을 고려할 수 있는 유일한 예외는 Airflow만 설치된 컨테이너 이미지를 빌드하는 경우예요 — 예를 들어 공식 컨테이너 이미지에 Airflow를 설치할 때가 그렇죠.
Constraints 파일 (Constraints files)
constraints가 왜 필요한가요?
Airflow® 설치는 Airflow가 라이브러리이자 애플리케이션이기 때문에 까다로울 수 있어요.
라이브러리는 보통 의존성을 열어두고 애플리케이션은 보통 고정(pin)하지만, 우리는 둘 다 하지도 않고 둘 다 해야 해요. 우리는 사용자가 필요하면 다른 버전의 라이브러리를 설치할 수 있도록 의존성을 최대한 열어두기로 했어요(pyproject.toml에서). 이는 때때로 그냥 pip install apache-airflow가 동작하지 않거나 사용할 수 없는 Airflow 설치를 만들어낼 수 있음을 의미해요.
Warning
Airflow 3.1부터 constraint 파일에는 테스트에서만 사용되는 pytest, moto 같은 개발자 의존성이 포함되지 않아요.
재현 가능한 Airflow 설치
재현 가능한 설치를 위해, 우리는 constraints-main, constraints-2-0, constraints-2-1 등 orphan 브랜치에 constraints 파일 세트를 유지하고, 각 릴리스 버전에 대한 태그(예: constraints-3.3.2)를 만든답니다.
이렇게 하면 릴리스 시점의 테스트된 의존성 세트를 유지해요. 이를 통해 릴리스 시점에 동작하는 것으로 알려진 Airflow + providers + dependencies의 정확히 동일한 설치 — 해당 Airflow 버전에 대한 동결된 의존성 세트 — 를 가질 수 있어요. Airflow가 지원하는 각 Python 버전마다 별도의 constraints 파일이 있어요.
아래 템플릿에서 변수를 대입해 파일 URL을 만들 수 있어요.
https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt
여기서:
AIRFLOW_VERSION- Airflow 버전 (예:3.3.2) 또는 최신 개발 버전용main,2-0PYTHON_VERSIONPython 버전, 예:3.10,3.11
아래 예시는 celery extra로 Airflow를 재현 가능하게 설치한다고 가정하지만, 자신만의 extra와 providers 세트를 선택할 수 있어요.
pip install "apache-airflow[celery]==3.3.2" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.3.2/constraints-3.10.txt"
Note
재현 가능한 설치는 올바른 Python 버전을 사용하고, 설치할 providers에 필요한 적절한 운영 체제 의존성이 설치되어 있다면, 이 초기 설치 단계가 항상 동작함을 보장해요. 일부 providers는 라이브러리를 컴파일하기 위해
build-essential, 또는 데이터베이스 provider를 설치할 때 데이터베이스 클라이언트 라이브러리 같은 추가 OS 의존성을 요구해요. 설치가 실패할 때 어떤 시스템 의존성이 필요한지 파악해 설치를 재시도하기 전에 설치해야 해요.
의존성 업그레이드 및 설치 (providers 포함)
위의 재현 가능한 설치는 providers 및 다른 의존성을 다른 버전으로 업그레이드하거나 다운그레이드하는 것을 막지 않아야 해요.
예를 들어 Airflow core 버전을 업그레이드하고 싶지 않더라도, 릴리스 후 새 버전의 providers와 의존성을 설치해 최신 버전을 사용하고 최신 보안 수정을 받을 수 있어요. 또는 호환성 이유로 이전 버전을 유지하고 싶다면 일부 의존성이나 providers를 다운그레이드할 수도 있어요. 그런 의존성 설치는 constraints 없이 별도의 pip 명령으로 해야 해요.
그런 업그레이드를 할 때는 설치할 패키지 목록에 apache-airflow 패키지를 추가하고 보유한 버전으로 고정해야 해요. 그렇지 않으면 pip가 의존성 해석을 수행할 때 자동으로 업그레이드/다운그레이드할 수 있어 기대와 다른 Airflow 버전이 될 수 있으니까요.
pip install "apache-airflow[celery]==3.3.2" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.3.2/constraints-3.10.txt"
pip install "apache-airflow==3.3.2" apache-airflow-providers-google==10.1.1
이 방식으로 다른 의존성도 다운그레이드하거나 업그레이드할 수 있어요 — 원래 constraints 파일에 저장된 것들과 호환되지 않더라도 말이죠:
pip install "apache-airflow[celery]==3.3.2" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.3.2/constraints-3.10.txt"
pip install "apache-airflow[celery]==3.3.2" dbt-core==0.20.0
Warning
모든 의존성이 이런 방식으로 설치될 수 있는 것은 아니에요 — Airflow의 기본 요구사항이나 시스템에 설치된 다른 의존성과 충돌하는 의존성이 있을 수 있어요. 하지만 의존성을 설치하거나 업그레이드할 때 constraints를 건너뛰면, Apache Airflow, providers 및 다른 의존성이 요구하는 한도 내에서 의존성을 유지하면서
pip가 충돌을 해석할 기회를 주게 돼요. 그 의존성과 constraints의 의존성 세트의 조합은 이전에 테스트되지 않았을 수 있지만, 우리가 보통 Airflow가 특정 버전의 일부 의존성에 의존할 때 요구사항을 추가하므로 대부분의 경우 동작할 거예요. 일부 의존성을 Airflow와 같은 환경에 설치할 수 없는 경우 다른 접근 방식을 시도할 수 있어요. 충돌하는/복잡한 Python 의존성 처리 모범 사례 참고.
설치된 의존성 검증하기
pip check 명령을 실행해 Python 패키지 세트가 일관되고 충돌하지 않는지 항상 테스트할 수 있어요.
> pip check
No broken requirements found.
이런 메시지가 보이고 pip check의 exit code가 0이면, 환경에 충돌하는 의존성이 없다는 것을 확신할 수 있어요.
자신만의 constraints 사용하기
자신의 의존성을 설치하거나 providers를 업그레이드/다운그레이드하기로 결정했다면, 단일 명령으로 Airflow와 그 의존성의 재현 가능한 설치를 계속 유지하고 싶을 수도 있어요. 이를 위해 자신만의 constraints 파일을 만들어 커뮤니티가 제공하는 것 대신 그 파일을 사용해 Airflow를 설치할 수 있어요.
pip install "apache-airflow[celery]==3.3.2" --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-3.3.2/constraints-3.10.txt"
pip install "apache-airflow==3.3.2" dbt-core==0.20.0
pip freeze > my-constraints.txt
그런 다음 로컬 constraints 파일을 통해 단일 작업으로 환경의 재현 가능한 설치를 만들 수 있어요:
pip install "apache-airflow[celery]==3.3.2" --constraint "my-constraints.txt"
Airflow 원래 constraints의 경우와 마찬가지로, 자신의 repository나 서버에 constraints를 호스팅하고 그곳에서 원격으로 사용할 수도 있어요.
릴리스 시점 constraints 고정하기 (Fixing Constraints at release time)
릴리스된 "버전이 지정된" constraints는 Airflow 버전을 릴리스할 때 대부분 고정되며, 예외적인 상황에서만 업데이트해요. 예를 들어 릴리스된 constraints가 Airflow가 처음부터 일관되게 설치되는 것을 방해할 수 있음을 발견한 경우 같은 경우예요.
정상적인 상황에서는 Airflow 의존성의 새 버전이 릴리스되더라도 constraint 파일이 변경되지 않아요 — 그 버전에 중요한 보안 수정이 포함되어 있더라도 말이죠. Airflow 릴리스 프로세스는 적용 가능한 곳에서 의존성을 자동으로 업그레이드하도록 설계되었지만, 이미 릴리스된 버전이 아니라 새 Airflow 버전을 릴리스할 때만 그래요.
릴리스 사이에 의존성을 직접 업그레이드할 수 있고, 이전 섹션에서 설명한 대로 자신의 constraints를 최신 상태로 유지할 수 있어요.
최신 릴리스 의존성을 따르는 가장 쉬운 방법은 최신 릴리스 Airflow 버전으로 업그레이드하는 거예요. 우리가 새 Airflow 버전을 릴리스할 때마다 모든 의존성을 최신 적절한 버전으로 업그레이드하고 함께 테스트하므로, 그 테스트를 따라가고 싶다면 — 최신 Airflow 버전을 유지하는 것이 그 의존성들을 업데이트하는 가장 쉬운 방법이에요.
설치 및 업그레이드 시나리오
설치를 단순화하기 위해 Airflow와 providers를 업그레이드하는 방법의 예시를 준비했어요.
extras와 providers로 Airflow® 설치하기
Airflow®의 extra 의존성을 설치해야 한다면 아래 스크립트로 설치를 한 줄로 만들 수 있어요 (아래 예시는 Postgres와 Google providers, 그리고 async extra를 설치해요):
AIRFLOW_VERSION=3.3.2
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[async,postgres,google]==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
이것은 이 Airflow 버전이 릴리스되었을 때 사용 가능했던 providers 버전을 설치한다는 점을 참고하세요. 이후에 릴리스된 providers를 업그레이드하려면 constraints 없이 별도의 pip 명령을 실행해야 해요.
Airflow를 providers와 함께 업그레이드하기
Airflow를 extras(설치 중인 Airflow 릴리스 시점에 사용 가능한 providers)와 함께 업그레이드할 수 있어요. 이렇게 하면 apache-airflow와 모든 providers를 설치 중인 Airflow 버전이 릴리스되었을 때 함께 릴리스되고 테스트된 버전으로 가져올 수 있어요.
AIRFLOW_VERSION=3.3.2
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[postgres,google]==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
Airflow core에서 providers를 별도로 관리하기
새 기능을 추가하거나, 버그 수정을 구현하거나, 역호환성을 유지하기 위해 Airflow Core 패키지와 별도로 providers를 설치, 업그레이드, 다운그레이드해야 할 수 있어요. 우리는 Airflow core와 독립적으로 providers를 릴리스하므로, 종종 새 providers 버전이 Airflow보다 먼저 릴리스되고, 아직 Airflow를 최신 버전으로 업그레이드하지 않으려면 새로 릴리스된 일부(또는 모든) providers만 별도로 설치하고 싶을 수 있어요.
위에서 봤듯이 providers를 별도로 설치할 때는 constraint 파일을 사용하지 말아야 해요.
환경을 자동으로 빌드한다면, Airflow가 설치된 후(보통 constraints와 함께) 별도 명령으로 provider를 설치해야 해요. Constraints는 함께 사용된 pip install 명령 동안에만 유효해요.
원래 이미지에서 오는 것과 같은 버전의 apache-airflow를 설치하는 것이 모범 사례예요. 이렇게 하면 pip가 다른 요구사항을 설치하는 동안 apache airflow를 다운그레이드하거나 업그레이드하지 않을 것을 확신할 수 있어요. 이는 사용 중인 apache-airflow 버전과 충돌하는 의존성을 추가하려 할 때 발생할 수 있어요:
pip install "apache-airflow==3.3.2" "apache-airflow-providers-google==8.0.0"
Note
providers를 별도로 설치, 업그레이드, 다운그레이드하는 것이 모든 Airflow 버전이나 다른 providers에서 동작한다는 보장은 없어요. 일부 providers는 최소 요구 Airflow 버전이 있고, 일부 providers 버전은 다른 providers나 설치된 의존성의 한계와 충돌하는 의존성 한계를 가질 수 있어요. 예를 들어 google provider는 10.1.0 버전 이전에는 protobuf 라이브러리의 한도
<=3.20.0가 있었지만, google이 지원하는google-ads라이브러리는 protobuf 라이브러리>=4를 요구해요. 그런 경우 이 두 의존성을 단일 환경에 함께 설치하면 동작하지 않아요. 그런 경우 다른 접근 방식을 시도할 수 있어요. 충돌하는/복잡한 Python 의존성 처리 모범 사례 참고.
providers 없이 Airflow core만 관리하기
어떤 providers도 설치하고 싶지 않다면, 필요한 버전의 Apache Airflow만 간단히 설치하거나 업그레이드할 수 있어요. 특수한 constraints-no-providers constraints 파일을 사용할 수 있는데, 이것은 더 작고 의존성을 Airflow core로만 제한해요. 하지만 환경에 이미 다른 버전의 일부 의존성이 설치되어 있고 다른 providers가 설치되어 있다면 충돌이 발생할 수 있어요. 그렇지만 이 명령은 Airflow가 릴리스될 당시 Airflow core와만 호환되는 최신 의존성 버전을 제공해요.
AIRFLOW_VERSION=3.3.2
PYTHON_VERSION="$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
# For example: 3.10
CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-no-providers-${PYTHON_VERSION}.txt"
# For example: https://raw.githubusercontent.com/apache/airflow/constraints-3.3.2/constraints-no-providers-3.10.txt
pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
문제 해결 (Troubleshooting)
이 섹션은 PyPI 설치와 관련된 설치 문제를 해결하는 방법을 설명해요.
'airflow' 명령이 인식되지 않습니다
airflow 명령이 인식되지 않으면(WSL을 사용하는 Windows에서 발생할 수 있어요), ~/.local/bin이 PATH 환경 변수에 있는지 확인하고, 필요하면 추가하세요:
PATH=$PATH:~/.local/bin
python -m airflow로 Airflow를 시작할 수도 있어요.
Symbol not found: _Py_GetArgcArgv
Airflow를 시작하거나 import할 때 Symbol not found: _Py_GetArgcArgv가 보이면, 호환되지 않는 버전의 Python을 사용하고 있다는 뜻일 수 있어요. homebrew로 설치된 Python의 경우, 일반적으로 /usr/local/opt/bin의 Python 대신 Frameworks 설비(예: python 3.10의 경우 /usr/local/opt/[email protected]/Frameworks/Python.framework/Versions/3.10)를 사용해야 합니다.
문제의 핵심은 Airflow가 의존하는 라이브러리 setproctitle이 표준 설치 /usr/local/opt/(/usr/local/Cellar 아래 경로로 symlink됨)에 없는 비공개 Python API를 사용한다는 거예요.
간단한 해결책은 Python 라이브러리의 dylib을 사용할 수 있는 Python 버전을 사용하도록 하는 거예요. 예를 들어:
# Note: these instructions are for python3.10 but can be loosely modified for other versions
brew install [email protected]
virtualenv -p /usr/local/opt/[email protected]/Frameworks/Python.framework/Versions/3.10/bin/python3 .toy-venv
source .toy-venv/bin/activate
pip install apache-airflow
python
>>> import setproctitle
# Success!
대안으로 Python 웹사이트에서 Python을 직접 다운로드해 설치할 수 있어요.