이 페이지에서는 커스텀 PyPI 패키지를 설치할 때 종속 항목 충돌 문제를 해결하는 방법을 설명합니다.
Cloud Composer에서 발생할 수 있는 PyPI 패키지와 관련된 가장 일반적인 문제는 종속 항목 충돌입니다.
설치할 새 커스텀 PyPI 패키지를 지정할 때 이 패키지 또는 해당 버전이 다른 커스텀 PyPI 패키지 또는 해당 환경에 사전 설치된 패키지와 종속 항목 충돌을 일으킬 수 있습니다. 이 경우 환경 업데이트 작업이 오류와 함께 실패합니다.
Cloud Build 및 클러스터 내 빌드 오류
패키지 관련 문제가 발생하면 해당 환경의 배포 방법에 따라 두 가지 방법으로 오류 메시지가 표시됩니다.
Cloud Build. 오류 메시지 및 Cloud Build 로그에 대한 링크가 표시됩니다. 예를 들면 다음과 같습니다.
UPDATE operation on this environment failed 25 minutes ago with the
following error message:
Failed to install PyPI packages. Check the Cloud Build log at ...
클러스터 내 빌드. 오류 메시지 및 빌드 로그의 위치가 표시됩니다. 예를 들면 다음과 같습니다.
UPDATE operation on this environment failed 17 minutes ago with the
following error message:
Failed to install PyPI packages. Check the in-cluster build logs for
details. They can be found in the Environment logs under the build-log-*
log name.
자세한 오류 메시지 보기
패키지 설치에 실패하면 pip가 자세한 오류 메시지를 보고합니다.
이 오류 메시지는 빌드 로그에서 찾을 수 있습니다.
ERROR: apache-airflow-backport-providers-google 2021.2.5 has requirement
google-cloud-logging<3.0.0,>=2.1.1, but you'll have google-cloud-logging
1.15.0 which is incompatible.
The command '/bin/sh -c bash installer.sh $COMPOSER_PYTHON_VERSION
fail' returned a non-zero code: 1
앞의 정보 메시지에는 자세한 pip 오류가 포함되어 있습니다. 예를 들면 다음과 같습니다.
apache-airflow-backport-providers-google 2021.2.5 has requirement
google-cloud-logging<3.0.0,>=2.1.1, but you have
google-cloud-logging 1.15.0.
Python 패키지 설치 중 타임아웃
최근 버전에서 pip 유틸리티는 종속 항목을 충족하려고 할 때 동작이 변경되었습니다. 지정된 종속 항목을 충족할 수 없는 경우 pip는 사용 가능한 모든 패키지 버전을 살펴봅니다.
패키지를 설치하면 다음과 같은 결과가 발생합니다.
패키지가 환경에 이미 사전 설치되어 있고 지정한 Python 종속 항목에 변경이 필요하지 않은 경우 패키지는 그대로 유지됩니다.
예: aiodebug==2.3.0가 설치되어 있고 aiodebug 또는 aiodebug>=2를 지정합니다.
패키지가 환경에 아직 설치되어 있지 않거나 지정한 Python 종속 항목을 충족하지 않으면 pip에서 종속 항목을 충족하는 최신 버전을 사용하려고 시도합니다. 버전을 지정하지 않은 경우 패키지의 최신 버전이거나 지정된 제한사항을 충족하는 패키지의 최신 버전입니다.
예: aiodebug를 지정하면 최신 버전(2.*.*)이 설치됩니다. aiodebug<2를 지정하면 1.*.* 이 설치됩니다.
이 버전이 사전 설치된 패키지와 종속 항목 충돌을 일으키는 경우 pip는 지정된 종속 항목을 충족하기 위해 패키지의 사용 가능한 모든 버전을 살펴봅니다. 이 문제가 발생하면 빌드 로그에 다음 메시지가 표시됩니다.
INFO: pip is looking at multiple versions of PYTHON_PACKAGE_NAME
to determine which version is compatible with other requirements.
This could take a while.
변경 전에는 다른 버전을 확인하지 않고 종속 항목 충돌로 인해 pip가 실패했습니다.
사용 가능한 모든 버전을 살펴보는 데 상당한 시간이 걸릴 수 있으며 Python 패키지 설치 중에 패키지 다운그레이드 또는 시간 초과가 발생할 수 있습니다.
Cloud Composer의 사전 설치된 패키지는 보안상의 이유로 최신 버전으로 정기적으로 업데이트됩니다. 따라서 환경을 이후 Cloud Composer 버전으로 업그레이드할 때도 타임아웃이 발생할 수 있습니다.
환경에서 커스텀 pip.conf 파일을 사용하는 경우 환경에 새 PyPI 패키지를 설치할 수 없는 문제가 발생할 수 있습니다. 패키지 설치 오류와 관련된 Cloud Build 로그에 다음 경고 메시지가 표시됩니다.
WARNING: Compute Engine Metadata server unavailable on attempt 3 of 3. Reason:
timed out
WARNING: Authentication failed using Compute Engine authentication due to
unavailable metadata server.
이 문제는 https://pypi.org/simple의 기본 패키지 색인에 대한 액세스를 허용하지 않는 pip.conf 파일로 인해 발생합니다. 예를 들어 pip.conf 파일에서 재정의된 index-url 매개변수로 인해 커스텀 Artifact Registry 저장소의 패키지 설치만 허용하는 경우 기본 패키지 색인에서 패키지를 설치할 수 없습니다.
이 문제를 해결하려면 https://pypi.org/simple 패키지 색인이 pip.conf 파일에 추가되어 있는지 확인합니다. 예를 들어 기본 패키지 색인이 index-url 매개변수에 정의되어 있으면 extra-index-url 매개변수에 https://pypi.org/simple 색인을 추가합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-03(UTC)"],[[["\u003cp\u003eThis document addresses dependency conflicts that occur when installing custom PyPI packages in Cloud Composer environments.\u003c/p\u003e\n"],["\u003cp\u003ePackage installation failures can be identified via error messages in either Cloud Build logs or in-cluster build logs, depending on the environment's deployment method.\u003c/p\u003e\n"],["\u003cp\u003eDependency conflicts often arise between newly installed custom PyPI packages and preinstalled packages, which can be resolved by installing alternative package versions, or by updating Cloud Composer versions.\u003c/p\u003e\n"],["\u003cp\u003eA custom \u003ccode\u003epip.conf\u003c/code\u003e file that restricts access to the default package index can prevent new package installations, and must have the \u003ccode\u003ehttp://pypi.org/simple\u003c/code\u003e index added.\u003c/p\u003e\n"]]],[],null,["# Troubleshooting PyPI package installation\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\n[Cloud Composer 3](/composer/docs/composer-3/troubleshooting-package-installation \"View this page for Cloud Composer 3\") \\| **Cloud Composer 2** \\| [Cloud Composer 1](/composer/docs/composer-1/troubleshooting-package-installation \"View this page for Cloud Composer 1\")\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis page explains how to troubleshoot dependency conflicts when installing\ncustom PyPI packages.\n\nThe most common problem with PyPI packages that you might encounter in\nCloud Composer are dependency conflicts.\n\nWhen you specify a new custom PyPI package to install, this package or its\nversion might cause dependency conflicts with other custom PyPI packages or\npreinstalled packages in your environment. In this case, the environment\nupdate operation fails with an error.\n\nCloud Build and in-cluster build errors\n---------------------------------------\n\nIf a problem with packages occurs, you get the error message about it in two\nways, depending on the way your environment is deployed:\n\n- **Cloud Build**. An error message and a link to the\n Cloud Build log. For example:\n\n UPDATE operation on this environment failed 25 minutes ago with the\n following error message:\n Failed to install PyPI packages. Check the Cloud Build log at ...\n\n- **In-cluster builds**. An error message and the location of build logs. For\n example:\n\n UPDATE operation on this environment failed 17 minutes ago with the\n following error message:\n Failed to install PyPI packages. Check the in-cluster build logs for\n details. They can be found in the Environment logs under the build-log-*\n log name.\n\nSee the detailed error message\n------------------------------\n\nWhen a package installation fails, `pip` reports the detailed error message.\nYou can find this error message in the build logs.\n\n### Locate the `pip` error in Cloud Build logs\n\nYou can follow the link from the Cloud Build error message, or\nlocate build logs:\n\n1. Locate build logs:\n\n 1. In Google Cloud console, go to the **Build history** page.\n\n [Go to Build history](https://console.cloud.google.com/cloud-build/builds)\n 2. Select the failed build to see its logs.\n\n2. In the build log, find the error message from `pip`. For example:\n\n ERROR: apache-airflow-backport-providers-google 2021.2.5 has requirement\n google-cloud-logging\u003c3.0.0,\u003e=2.1.1, but you'll have google-cloud-logging\n 1.15.0 which is incompatible.\n\n### Locate the `pip` error in in-cluster build logs\n\n1. Locate build logs:\n\n 1. In Google Cloud console, go to the **Environments** page.\n\n [Go to Environments](https://console.cloud.google.com/composer/environments)\n 2. Select your environment.\n\n 3. Open the **Logs** tab.\n\n 4. Select **All logs** \\\u003e **Composer logs** \\\u003e **Builds** \\\u003e\n **Worker \\& Scheduler image**.\n\n 5. In the **Severity** drop-down list, select **Info**.\n\n2. In the displayed logs:\n\n 1. Locate the `installer.sh` error message. For\n example:\n\n The command '/bin/sh -c bash installer.sh $COMPOSER_PYTHON_VERSION\n fail' returned a non-zero code: 1\n\n 2. The preceding info messages have the detailed `pip` error. For\n example:\n\n apache-airflow-backport-providers-google 2021.2.5 has requirement\n google-cloud-logging\u003c3.0.0,\u003e=2.1.1, but you have\n google-cloud-logging 1.15.0.\n\nTimeouts during Python package installation\n-------------------------------------------\n\nIn recent versions, the `pip` utility changed its behavior when attempting to\nsatisfy dependencies. If specified dependencies can't be satisfied, `pip` goes\nthrough all available versions of a package.\n\nWhen you install a package, the following happens:\n\n1. If the package is [already preinstalled](/composer/docs/composer-versions) in your environment\n and Python dependencies that you specify don't require any changes, the\n package remains as it is.\n\n Example: `aiodebug==2.3.0` is installed and you specify `aiodebug` or\n `aiodebug\u003e=2`.\n2. If the package isn't already installed in your environment or it doesn't\n satisfy Python dependencies you specify, then `pip` tries to use the\n latest version that satisfies dependencies. This is either the latest\n version of the package if you didn't specify a version, or the latest\n version of the package that satisfies the specified restrictions.\n\n Example: If you specify `aiodebug`, then the latest will be installed\n (2.\\*.\\*). If you specify `aiodebug\u003c2`, then 1.\\*.\\* will be installed.\n\n If this version causes dependency conflicts with preinstalled packages,\n `pip` **goes through all available versions** of the package to try to\n satisfy the specified dependency. When it happens, the following messages\n will be visible in the build log: \n\n INFO: pip is looking at multiple versions of PYTHON_PACKAGE_NAME\n to determine which version is compatible with other requirements.\n This could take a while.\n\n Before the change, `pip` failed with a dependency conflict without checking\n other versions.\n\nGoing through all available versions can take a significant amount of time and\nlead to a downgrade of packages or to a timeout during the Python package\ninstallation.\n\nPreinstalled packages in Cloud Composer are regularly updated\nto the latest versions for security reasons. Therefore, a timeout can also\noccur when you upgrade an environment to a later Cloud Composer\nversion.\n\n**Possible solutions:**\n\n- Regularly update custom Python dependencies.\n\n- Use [PythonVirtualenvOperator](https://airflow.apache.org/docs/apache-airflow/stable/howto/operator/python.html#pythonvirtualenvoperator)\n to isolate code snippets that require conflicting packages.\n\nConflicts with preinstalled PyPI packages\n-----------------------------------------\n\nSome package conflicts occur between custom PyPI packages that you install and\nthe preinstalled packages.\n\nYou can see the full list of preinstalled packages for your version of\nCloud Composer on the\n[Cloud Composer versions](/composer/docs/composer-versions) page.\n\nTo solve this problem, you can:\n\n- Install a different version of the custom PyPI package.\n\n- Install a different version of the preinstalled package. To do so,\n [install a custom PyPI package](/composer/docs/composer-2/install-python-dependencies#install-pypi)\n with the name of the preinstalled package and specify the required version.\n We do not recommend downgrading preinstalled packages.\n\n- See if later [Cloud Composer versions](/composer/docs/composer-versions) use a different\n version of the preinstalled package. You can\n [check for potential PyPI package conflicts](/composer/docs/composer-2/upgrade-environments#upgrade-check)\n before you upgrade your environment to a later version of\n Cloud Composer.\n\n- Use [PythonVirtualenvOperator](https://airflow.apache.org/docs/apache-airflow/stable/howto/operator/python.html#pythonvirtualenvoperator)\n to isolate code snippets that require conflicting packages.\n\nMetadata server unavailable when installing PyPI packages\n---------------------------------------------------------\n\nIf your environment uses a [custom `pip.conf` file](/composer/docs/composer-2/install-python-dependencies),\nthen you might face a problem when no new PyPI packages can be installed in\nyour environment. In Cloud Build logs related to the package\ninstallation error, you can see the following warning message: \n\n WARNING: Compute Engine Metadata server unavailable on attempt 3 of 3. Reason:\n timed out\n WARNING: Authentication failed using Compute Engine authentication due to\n unavailable metadata server.\n\nThis problem is caused by a `pip.conf` file that does not allow access to the\n[default package index](https://pypi.org/simple)\nat `https://pypi.org/simple`. For example, if your `pip.conf` file only\npermits installing packages from a custom Artifact Registry repository because of\nthe redefined `index-url` parameter, installing packages from the\ndefault package index is not available.\n\nTo solve this problem, make sure that `https://pypi.org/simple` package index\nis added to your `pip.conf` file. For example, if your primary package index\nis defined in the `index-url` parameter, add the `https://pypi.org/simple`\nindex in the `extra-index-url` parameter.\n| **Warning:** When using `extra-index-url` parameter, make sure that the packages are installed from the repository you want to use. Sometimes, usage of `extra-index-url` parameter might lead to [Dependency Confusion](/software-supply-chain-security/docs/dependencies#public-dependencies) situations where a different version of a package might be installed than originally intended.\n\nWhat's next\n-----------\n\n- [Installing Python dependencies](/composer/docs/composer-2/install-python-dependencies)\n- [Troubleshooting environment updates and upgrades](/composer/docs/composer-2/troubleshooting-updates-upgrades)"]]
