Qiskit v1.0 패키지의 주요 변경 사항 이해하기

Qiskit v1.0은 이전 버전의 Qiskit과 다른 패키징 구조를 사용하며, Qiskit v1.0을 지원하지 않는 패키지를 사용하는 환경에서는 문제가 발생할 가능성이 높습니다.

주의

기존 Python 가상 환경을 Qiskit v1.0으로 직접 업그레이드하지 마세요.

앞으로 이와 같은 주요 패키징 변경은 하지 않을 예정입니다. 이번 변경은 Qiskit v1.0 출시 시점의 일회성 이벤트로, 향후 패키징 과정을 최대한 간소화하기 위한 것입니다.

이 페이지에는 v1.0 이전의 Qiskit 패키지에 대한 자세한 정보와 주요 패키징 변경을 결정한 이유가 담겨 있습니다.

이 변경이 불편을 초래한다는 점을 충분히 알고 있지만, 이를 통해 Qiskit은 대부분의 Python 패키지가 사용하는 단순한 패키지 구조로 돌아가게 됩니다. Qiskit v1.0 전환이 완료되면 사용자, 개발자, 라이브러리 작성자 모두에게 더 편리한 환경이 제공될 것입니다.

서문: Python 패키징 용어 해설

기존 Qiskit 메타패키지의 구조와 Qiskit v1.0 출시로 달라진 점을 보다 명확하게 설명하기 위해, 자주 사용되는 Python 패키징 전문 용어 해설을 아래에 정리했습니다. 다음 용어들은 이 문서에서 특정 의미로 사용됩니다.

이 페이지의 용어 해설을 보려면 여기를 클릭하세요

• 모듈(module): 단일 Python 파일입니다.

• 패키지(package): __init__.py와 Python이 읽을 수 있는 다른 파일 또는 패키지를 포함하는 디렉터리입니다. 이것은 컴퓨터에 설치된 실제 코드이며, import something을 실행할 때 동작하는 코드입니다. Python은 검색 경로에 있는 모든 디렉터리를 import할 수 있는 대상으로 간주합니다(그리고 많은 추가 항목을 import합니다).

  이것은 pip install로 설치하는 객체(즉, 배포판)와 동일하지 않지만, 일반적으로 pip install로 설치하는 것과 import하는 것은 동일한 이름을 가집니다.

• 서브모듈(submodule), 서브패키지(subpackage): 정확한 용어는 아니지만 일반적으로 사용됩니다. sub 접두사는 "패키지 내에 포함된"을 의미합니다. 서브모듈은 모듈이고 서브패키지는 패키지이지만, 더 큰 패키지의 일부입니다.

• 네임스페이스 패키지(namespace package): 다른 _배포판_이 서브모듈이나 서브패키지를 설치할 수 있는 패키지입니다. 중요한 점은, 네임스페이스 패키지에 기여하는 어떤 배포판도 설치된 파일 전체를 반드시 소유하지 않기 때문에, 완전히 제거하거나 업그레이드하기가 까다로울 수 있습니다.

• 배포판(distribution): pip install something을 실행할 때 다운로드되는 압축된 Python 파일, 데이터 파일, 메타데이터의 집합입니다. 일반적으로 배포판에는 정확히 하나의 패키지와 설치 방법에 대한 메타데이터(요구 사항 등)가 포함되어 있지만, 반드시 그런 것은 아닙니다. 배포판에는 0개 이상의 모듈이나 패키지가 포함될 수 있습니다.

  Debian/Ubuntu의 apt나 macOS의 Homebrew와 같이 Python 이외의 "패키지 관리자"에 익숙하다면, 그들이 "패키지"라고 부르는 것을 Python에서는 배포판이라고 하며, Python이 패키지라고 부르는 것과 정확히 일치하는 개념은 없습니다.

  Python 패키징에 관해 이야기하는 대부분의 자료는 배포판과 패키지 모두를 _패키지_라는 용어로 사용하므로, 문맥을 통해 의미를 파악해야 합니다. 일반적으로 import하는 경우 해당 자료는 "패키지"를 의미하고, pip install하는 경우 "배포판"을 의미합니다.

• 검색 경로(search path): import something을 시도할 때, Python은 미리 정의된 위치 목록에서 something이라는 모듈 또는 패키지를 검색합니다. 그 위치 목록이 _검색 경로_입니다. sys.path에서 검색 경로를 확인하고 수정할 수 있습니다.

• 요구 사항(requirement): 배포판에는 설치 시 의존하는 다른 배포판에 대한 정보가 포함되어 있습니다. 필요한 다른 배포판은 _요구 사항_이라고 하며, 패키지 관리자(보통 pip 또는 conda)는 모든 요구 사항이 호환 가능한 버전으로 설치되어 있는지 확인해야 합니다.

Python은 매우 동적이며, 예를 들어 모듈 또는 패키지가 디스크의 파일에 대응하지 않거나, 컴파일된 확장 모듈인 경우 등 다양한 복잡한 상황이 발생할 수 있습니다.

검색 경로는 단순히 디렉터리를 검색하는 것뿐만 아니라 다양한 방식으로 동작하지만, 이 논의에서는 디스크의 파일만 관련이 있습니다. 이 섹션에서 설명하는 문제를 이해하는 데 추가적인 복잡성은 필요하지 않으므로, 위에서 설명한 모델을 사용하면 됩니다.

기존 Qiskit 구조

역사적으로 Qiskit은 여러 Python 배포판으로 구성되어 있었습니다: 컴파일러 코어인 qiskit-terra, 고성능 시뮬레이터인 qiskit-aer, 최초의 IBM Quantum® 제공자, 그리고 특정 탐색적 알고리즘 또는 실험 실행 기능을 제공하는 현재는 더 이상 사용되지 않는 여러 패키지가 있었습니다. 사용자의 편의를 위해, 자체 코드는 포함하지 않지만 다른 모든 구성 요소가 설치되도록 하는 qiskit이라는 Python 배포판도 제공했습니다. 다른 패키지 관리자의 유사한 개념에서 유추하여, 이를 _메타패키지_라고 불렀습니다. Qiskit 코어의 코드는 Python 패키지 qiskit의 루트를 소유한 qiskit-terra에 있었습니다. 즉, qiskit-terra는 import qiskit을 실행할 때 일어나는 일을 제어했습니다. Qiskit v1.0 이전까지, qiskit 패키지는 네임스페이스 패키지였으며 qiskit.providers에 두 번째 네임스페이스 패키지를 포함했습니다.

이러한 구조는 우리와 사용자 모두에게 상당한 문제를 일으켰습니다.

예를 들어, Qiskit에 의존하는 다운스트림 라이브러리들은 실제로 컴파일러 코어만 필요한 경우가 많았으며, pip install qiskit에 포함된 대규모 생태계 전체를 요구하지 않았습니다. 따라서 이들은 올바르게 요구 사항을 qiskit-terra로 명시했습니다. 그러나 사용자들이 pip uninstall qiskit을 실행하여 Qiskit을 제거하려 할 때 pip에서 문제가 발생했습니다:

• pip는 더 이상 사용되지 않는 배포판을 제거하지 않습니다. 따라서 pip uninstall qiskit은 거의 아무것도 하지 않았습니다. 배포판에 코드가 없었으므로 제거되는 코드도 없었습니다.
• 코드를 제거하더라도, qiskit-terra에 의존하는 많은 다운스트림 배포판이 설치된 상태로 남아 있게 됩니다.
• qiskit-terra가 제거되더라도, 네임스페이스 패키지였기 때문에 사용 가능한 코드가 없는 import 가능한 qiskit 디렉터리가 남아 있을 수 있습니다.

pip install 명령으로 배포판을 설치하거나 업그레이드할 때, pip는 이전 요구 사항 해석을 고려하지 않습니다. 두 개의 패키지가 있었기 때문에, qiskit-terra 업그레이드를 요구하는 패키지를 업그레이드하면 유효하지 않은 환경이 만들어졌습니다. pip는 qiskit-terra를 업그레이드했지만 qiskit은 그대로 두었습니다. 이후 모든 pip install 명령 실행 시 경고를 표시했지만, 아무것도 이상해 보이지 않았기 때문에 사용자들은 일반적으로 경고를 무시했고, pip는 오류 상태를 발생시키거나 작업을 금지하지 않았습니다.

시간이 지남에 따라, qiskit 메타패키지에서 요소들을 제거하여 Qiskit v0.44부터는 qiskit-terra만 남게 되었습니다. 이 구성 요소 중 qiskit-aer은 여전히 존재하며 활발히 업데이트되고 있지만, 이제는 별도의 배포판으로 설치됩니다.

마찬가지로, 다른 라이브러리가 네임스페이스 훅을 사용하는 것을 점점 더 강하게 권장하지 않게 되었습니다. Qiskit Aer v0.11 출시 및 새로운 qiskit_aer Python 패키지와 함께 더 이상 사용되지 않는 패키지가 아닌 패키지에서 훅의 마지막 Qiskit 사용을 제거했으며, Qiskit v1.0 이전까지는 네임스페이스 경로 qiskit.providers.aer도 강제로 동작하도록 했습니다. Qiskit v1.0부터는 패키지가 qiskit 네임스페이스를 확장하는 기능을 제거했습니다. 따라서 유효한 환경에서 올바른 배포판에 대해 pip uninstall을 실행하면 이제 예상대로 작동합니다.

새로운 Qiskit 구조

버전 1.0부터 Qiskit은 qiskit이라는 단일 배포판으로 구성되며, 이 배포판은 디렉터리 내의 모든 코드를 소유하는 qiskit이라는 단일 패키지를 설치합니다. 이것이 Python 코드의 일반적인 구조이며, 가장 단순하고 오류가 발생하기 어려운 구조입니다.

PyPI의 qiskit-terra 배포판은 버전 1.0 이상으로 업데이트되지 않을 것입니다. 이는 완전히 qiskit으로 대체되었습니다. qiskit-terra라는 이름은 더 이상 설치에 관여하지 않습니다. 그러나 qiskit-terra 패키지는 PyPI에서 제거되지 않으며, 오래된 과학 코드와 레거시 패키지가 계속 사용할 수 있도록 최신 버전을 작동 상태로 유지할 것입니다.

안타깝게도, 메타패키지 레거시와 패키지 관리자로서의 pip 결함으로 인해, 특히 일부 패키지는 이전 버전의 Qiskit에 의존하고 일부는 Qiskit v1.0 이상만 요구하는 상황에서 사용자들이 Qiskit v1.0으로 완전히 원활하게 업그레이드할 수 있는 경로를 제공하기가 불가능합니다. 더 많은 생태계가 Qiskit v1.0으로 마이그레이션됨에 따라 이러한 문제는 줄어들 것입니다.

애플리케이션 모듈은 어디로 갔나요?

pip install qiskit 명령이 더 이상 qiskit-aer나 qiskit-nature와 같은 패키지를 포함하지 않는다는 것을 알게 될 수 있습니다. 메타패키지 구조가 제거됨에 따라, 이러한 패키지들 중 많은 것들이 별도로 설치해야 하는 배포판으로 분리되었습니다.

Qiskit SDK v1.0 출시 이전에는, Qiskit이 컴파일러 코어인 qiskit-terra, 고성능 시뮬레이터인 qiskit-aer, 최초의 IBM Quantum® 제공자, 그리고 특정 탐색적 알고리즘 또는 실험 실행 기능을 제공하는 현재는 더 이상 사용되지 않는 여러 패키지 등 많은 Python 배포판으로 구성되어 있었습니다.

이전에 Qiskit 메타패키지에 포함되었던 패키지들을 설치하려면, Qiskit 생태계를 방문하여 필요에 맞는 다양한 패키지를 찾아보세요. 새 배포판 설치 방법에 대한 자세한 내용은 v1.0 마이그레이션 가이드를 참조하세요.