노트북에 한정된 Python 라이브러리

Notebook 범위 라이브러리를 사용하면 Notebook에 특정한 사용자 지정 Python 환경을 만들기, 수정, 저장, 재사용 및 공유할 수 있습니다. Notebook 범위 라이브러리를 설치하면 현재 Notebook 및 해당 Notebook과 연결된 모든 작업만 해당 라이브러리에 액세스할 수 있습니다. 동일한 클러스터에 연결된 다른 Notebooks는 영향을 받지 않습니다.

노트북 범위의 라이브러리는 세션 간에 유지되지 않습니다. 각 세션이 시작될 때 또는 Notebook이 클러스터에서 분리될 때마다 Notebook 범위 라이브러리를 다시 설치해야 합니다.

Databricks는 노트북 범위의 Python 라이브러리를 설치하기 위해 %pip 매직 명령을 사용할 것을 권장합니다. 환경 버전 5 이상을 실행하는 서버리스 Notebook에서 더 빠른 설치에 사용할 %uv pip 수도 있습니다.

작업으로 예약된 Notebook에서 %pip를 사용할 수 있습니다. Scala, SQL 또는 R 노트북에서 Python 환경을 관리해야 하는 경우 %python 매직 명령을 %pip와 함께 사용하세요.

노트북 범위의 라이브러리 설치를 사용할 때 드라이버 노드로의 트래픽이 더 많아질 수 있습니다. 드라이버 노드 크기 권장 사항을 참조하세요.

클러스터에 연결된 모든 Notebook에 대한 라이브러리를 설치하려면 클러스터 라이브러리를 사용합니다. 컴퓨팅 범위 라이브러리를 참조하십시오.

Databricks에서 Python 라이브러리를 설치하는 데 사용할 수 있는 옵션에 대한 포괄적인 개요는 Python 환경 관리를 참조하세요.

%pip 명령을 사용하여 라이브러리 관리

%pip 명령은 pip 명령과 동일하며 동일한 API를 지원합니다. 다음 섹션에서는 %pip 명령을 사용하여 환경을 관리하는 방법의 예를 보여 줍니다. pip를 사용하여 Python 패키지를 설치하는 방법에 대한 자세한 내용은 pip 설치 설명서 및 관련 페이지를 참조하세요.

중요합니다

  • %pip 명령은 Python 프로세스를 자동으로 다시 시작하지 않습니다. 새 패키지를 설치하거나 기존 패키지를 업데이트한 경우 새 패키지를 확인하려면 dbutils.library.restartPython()를 사용해야 할 수 있습니다. Azure Databricks에서 Python 프로세스 다시 시작을 참조하세요.
  • %pip를 사용하여 핵심 Python 패키지(예: IPython)를 업그레이드, 수정 또는 제거하면 일부 기능이 예상대로 작동하지 않을 수 있습니다. 이러한 문제가 발생하는 경우 클러스터를 다시 시작하거나 새 세션을 시작하여 환경을 다시 설정합니다.

를 사용하여 더 빠르게 설치 %uv pip

참고

%uv pip 는 환경 버전 5 이상을 실행하는 서버리스 Notebook에서만 사용할 수 있습니다. 클래식 컴퓨팅 및 이전 서버리스 환경 버전은 %uv pip를 지원하지 않습니다.

%uv pip 매직 명령은 .에 대한 더 빠른 대안%pip입니다. %uv pip 는 uv 패키지 관리자에 의해 구동되고 동일한 Notebook 가상 환경을 %pip공유하므로 한 도구와 함께 설치된 패키지가 다른 도구에 표시됩니다.

%uv pip는 설치 및 읽기 전용 작업(예: %pip.)보다 list 빠릅니다. 따라서 환경 사양을 기반으로 반복하는 데 적합합니다.

%uv pip는 표준 pip 하위 명령, 즉 , install, uninstalllist, showfreeze및 check를 지원합니다tree.

%uv pip install simplejson

%uv pip list

이 페이지의 다른 설치 패턴(볼륨, 작업 영역 파일, 요구 사항 파일, 버전 제어, 프라이빗 리포지토리)은 함께 %uv pip작동합니다. 이 예시들에서는 %pip를 %uv pip로 바꿀 수 있습니다.

%uv pip 제한

  • %uv pip uninstall 는 서버리스 환경에 미리 설치된 라이브러리를 완전히 제거할 수 없습니다. 패키지 메타데이터만 제거됩니다. 기본 파일은 파일 시스템에 남아 있으며 패키지는 여전히 가져올 수 있습니다.
  • %uv pip 는 사전 설치된 라이브러리에 대한 종속성 충돌을 확인하지 않습니다.
  • %uv pip 명령어를 실행한 후 노트북의 환경 사이드 패널에 미리 설치된 일부 라이브러리가 사용자가 설치한 것으로 표시될 수 있습니다. 이는 표시 문제이며 패키지 기능에 영향을 주지 않습니다.
  • %uv pip 는 빠른 대화형 반복을 위한 것입니다. Notebook에 대해 재현 가능한 환경을 설정하려면 Notebook의 환경 쪽 패널에 종속성을 추가합니다.

%pip를 사용하여 라이브러리 설치

%pip install matplotlib

%pip로 Python wheel 패키지 설치하기

%pip install /path/to/my_package.whl

%pip를 사용하여 라이브러리 제거

참고

Databricks Runtime 릴리스 정보의 버전 및 호환성에 포함된 라이브러리나 클러스터 라이브러리로 설치된 라이브러리는 제거할 수 없습니다. Databricks Runtime에 포함된 버전이나 클러스터에 설치된 것과 다른 라이브러리 버전을 설치한 경우 %pip uninstall을 사용하여 라이브러리를 Databricks Runtime의 기본 버전이나 클러스터에 설치된 버전으로 되돌릴 수 있지만 %pip 명령을 사용하여 Databricks Runtime에 포함되거나 클러스터에 설치된 라이브러리 버전을 제거할 수 없습니다.

%pip uninstall -y matplotlib

-y 옵션은 필수입니다.

%pip를 사용하여 버전 제어 시스템에서 라이브러리 설치

%pip install git+https://github.com/databricks/databricks-cli

URL에 매개 변수를 추가하여 버전 또는 git 하위 디렉터리와 같은 항목을 지정할 수 있습니다. 자세한 내용과 다른 버전 제어 시스템 사용 예는 VCS 지원을 참조하세요.

Databricks 시크릿으로 관리되는 자격 증명을 사용해 프라이빗 패키지를 설치%pip

pip는 프라이빗 버전 제어 시스템 및 프라이빗 패키지 리포지토리(예: Nexus 및 Artifactory등) 기본 인증사용하여 프라이빗 원본에서 패키지 설치를 지원합니다. 비밀 관리는 인증 토큰과 비밀을 저장할 수 있는 Databricks Secrets API를 통해 사용할 수 있습니다. DBUtils API를 사용하여 Notebook의 보안 비밀에 액세스합니다. 매직 명령에서 $variables를 사용할 수 있습니다.

프라이빗 리포지토리에서 패키지를 설치하려면 --index-url 옵션을 사용하여 리포지토리 URL을 %pip install에 지정하거나 pip의 ~/.pip/pip.conf 구성 파일에 추가합니다.

token = dbutils.secrets.get(scope="scope", key="key")

%pip install --index-url https://<user>:$token@<your-package-repository>.com/<path/to/repo> <package>==<version> --extra-index-url https://pypi.org/simple/

마찬가지로 매직 명령과 함께 비밀 관리를 사용하여 버전 제어 시스템에서 프라이빗 패키지를 설치할 수 있습니다.

token = dbutils.secrets.get(scope="scope", key="key")

%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>

%pip를 사용하여 DBFS에서 패키지 설치

중요합니다

모든 작업 영역 사용자는 DBFS에 저장된 파일을 수정할 수 있습니다. Azure Databricks는 작업 영역 또는 Unity 카탈로그 볼륨에 파일을 저장하는 것이 좋습니다.

%pip를 사용하여 DBFS에 저장된 프라이빗 패키지를 설치할 수 있습니다.

DBFS에 파일을 업로드하면 파일 이름이 자동으로 변경되어 공백, 마침표 및 하이픈이 밑줄로 바뀝니다. Python 휠 파일의 경우 pip에서는 파일 이름에서 버전에 마침표(예: 0.1.0)를 사용하고 공백이나 밑줄(_) 대신 하이픈을 사용해야 하므로 이러한 파일 이름은 변경되지 않습니다.

%pip install /dbfs/mypackage-0.0.1-py3-none-any.whl

를 사용하여 볼륨에서 패키지 설치 %pip

중요합니다

이 기능은 공개 미리 보기 상태입니다.

Databricks Runtime 13.3 LTS 이상을 사용하면 볼륨에 저장된 프라이빗 패키지를 설치하는 데 사용할 %pip 수 있습니다.

볼륨에 파일을 업로드하면 파일의 이름이 자동으로 바뀌고 공백, 마침표 및 하이픈이 밑줄로 바뀝니다. Python 휠 파일의 경우, pip에서는 파일 이름에 버전 표기 시 마침표(예: 0.1.0)를 사용하고 공백이나 밑줄 대신 하이픈을 사용해야 하므로 이러한 파일 이름은 변경되지 않습니다.

%pip install /Volumes/<catalog>/<schema>/<path-to-library>/mypackage-0.0.1-py3-none-any.whl

작업 영역 파일로 저장된 패키지 설치 %pip

Databricks Runtime 11.3 LTS 이상을 사용하면 %pip 작업 영역 파일로 저장된 프라이빗 패키지를 설치할 수 있습니다.

%pip install /Workspace/<path-to-whl-file>/mypackage-0.0.1-py3-none-any.whl

요구 사항 파일에 라이브러리 저장

%pip freeze > /Workspace/shared/prod_requirements.txt

파일 경로의 모든 하위 디렉터리가 이미 있어야 합니다. %pip freeze > /Workspace/<new-directory>/requirements.txt를 실행하는 경우 /Workspace/<new-directory> 디렉터리가 아직 없으면 명령이 실패합니다.

요구 사항 파일을 사용하여 라이브러리 설치

요구 사항 파일에는 pip를 사용하여 설치할 패키지 목록이 포함되어 있습니다. 요구 사항 파일을 사용하는 예는 다음과 같습니다.

%pip install -r /Workspace/shared/prod_requirements.txt

requirements.txt 파일에 대한 자세한 내용은 요구 사항 파일 형식을 참조하세요.

드라이버 노드 크기 권장 사항

노트북 범위의 라이브러리를 사용하면 드라이버 노드가 실행기 노드 전반에서 환경의 일관성을 유지하기 위해 작업해야 하므로 드라이버 노드로의 트래픽이 더 많아질 수 있습니다.

10개 이상의 노드가 있는 클러스터를 사용하는 경우 Databricks는 드라이버 노드에 대한 최소 요구 사항으로 다음 사양을 권장합니다.

  • 100개 노드 CPU 클러스터의 경우 Standard_D8ds_v5 사용합니다.
  • 10노드 GPU 클러스터의 경우 Standard_NC12를 사용합니다.

더 큰 클러스터의 경우 더 큰 드라이버 노드를 사용합니다.

%pip, %sh pip, !pip의 차이점

%sh 및 !는 Notebook에서 셸 명령을 실행합니다. 전자는 Databricks 보조 매직 명령이고 후자는 IPython의 기능입니다. automagic가 사용 설정된 경우 pip는 %pip의 약식 표현이며, 이는 Azure Databricks Python 노트북에서 기본값입니다.

Databricks Runtime 11.3 LTS 이상에서는 %pip, %sh pip, !pip는 모두 라이브러리를 노트북 범위의 Python 라이브러리로 설치합니다. Databricks Runtime 10.4 LTS 및 그 이하 버전에서는 노트북 범위 라이브러리를 설치하려면 %pip 또는 pip만 사용할 것을 Databricks는 권장합니다. %sh pip 및 !pip의 동작은 Databricks Runtime 10.4 LTS 이하에서 일관되지 않습니다.

알려진 문제

  • Databricks Runtime 9.1 LTS에서는 노트북 범위의 라이브러리가 배치 스트리밍 작업과 호환되지 않습니다. Databricks에서는 클러스터 라이브러리 또는 IPython 커널을 대신 사용하는 것이 좋습니다.
  • Last updated on