Qiskit 설치

로컬 환경이나 클라우드 환경에서 작업할 예정이든 관계없이, 모든 사용자가 가장 먼저 해야 할 일은 Qiskit을 설치하는 것입니다.

Qiskit 0.x에서 Qiskit 1.0 이상으로 업그레이드

(처음으로 Qiskit을 설치하는 경우, 설치 및 설정 섹션으로 건너뛰세요. 이 안내는 이전에 Qiskit을 설치한 사용자에게만 해당됩니다.)

버전 0.x에서 1.0 이상으로 업그레이드하는 분들께: Qiskit v1.0은 새로운 패키징 구조를 사용하므로, Qiskit 0.x 버전에서 1.0으로 업그레이드할 때 pip install -U qiskit 명령을 사용할 수 없습니다.

자세한 내용과 지침은 Qiskit 1.0 마이그레이션 가이드를 참고하세요.

Qiskit 1.0부터 시작하는 향후 업데이트에서는 제자리 업그레이드가 가능해질 예정입니다.

Qiskit SDK와 Qiskit Runtime 클라이언트 설치

Python을 설치합니다. Qiskit PyPI 프로젝트 페이지의 "Programming Language" 섹션에서 최신 릴리스가 지원하는 Python 버전을 확인하세요. 다운로드 방법은 Python 초보자 가이드를 참고하세요.

다른 애플리케이션과 Qiskit을 분리하기 위해 Python 가상 환경을 사용하는 것을 권장합니다.

참고
이 지침은 pypi.org의 표준 Python 배포판을 사용합니다. 하지만 Anaconda나 miniconda 같은 다른 Python 배포판과 Poetry 같은 다른 의존성 관리 워크플로우를 사용할 수도 있습니다.

가상 환경이 처음이시라면, 여기를 클릭하여 자세한 내용을 확인하세요.
Python 가상 환경은 특정 목적을 위해 Python을 사용하는 격리된 공간으로, 머신의 "기본" Python 환경에 영향을 주지 않고 원하는 패키지를 설치하고 라이브러리, 의존성 등을 설정할 수 있습니다.
가상 환경의 중요한 장점 중 하나는 Python 환경이 어느 순간에 손상되더라도 가상 환경을 쉽게 삭제하고 다시 시작할 수 있다는 점입니다!
가상 환경에 대한 정보를 저장할 위치를 선택하세요. 일반적으로 작업 중인 각 프로젝트 디렉터리 내의 .venv 디렉터리에 저장됩니다.

먼저, 프로젝트 디렉터리로 이동하여 Python만 설치된 최소 환경을 만드세요.
- macOS
- Linux
- Windows
python3 -m venv .venv
python3 -m venv .venv
python -m venv .venv
다음으로, 새 환경을 활성화하세요.
- macOS
- Linux
- Windows
source .venv/bin/activate
source .venv/bin/activate
PowerShell을 사용하는 경우:
.venv\Scripts\Activate.ps1
Git Bash를 사용하는 경우:
source .venv/scripts/activate
명령 프롬프트를 사용하는 경우:
.venv\Scripts\activate
환경에 pip이 아직 설치되지 않은 경우 pip을 설치하세요. pip은 Qiskit 및 기타 Python 패키지를 설치하는 데 사용하는 Python 패키지 관리자입니다. pip list를 사용하여 가상 환경에 무엇이 있는지 확인할 수 있습니다. 대부분의 Python 환경에는 pip이 이미 설치되어 있습니다.
Qiskit SDK를 설치합니다. 양자 하드웨어에서 작업을 실행할 계획이라면 Qiskit Runtime도 함께 설치하세요.
```
pip install qiskit
```
```
pip install qiskit-ibm-runtime
```
시각화 지원 추가
시각화 기능이나 Jupyter 노트북을 사용하려면 qiskit.visualization 모듈도 설치하세요. 자세한 내용은 Visualizations API 참조를 확인하세요.

방금 설치한 Qiskit 패키지로 Jupyter 노트북을 실행하려면 환경에 Jupyter를 설치해야 합니다.
```
pip install jupyter
```
그런 다음 다음과 같이 노트북을 여세요:
```
jupyter notebook <path/to/notebook.ipynb>
```

로컬에서 작업하고 Qiskit에 내장된 시뮬레이터를 사용할 계획이라면 설치가 완료된 것입니다. IBM QPU에서 작업을 실행하려면 계속해서 IBM Cloud 계정 설정으로 진행하세요.

최신 버전으로 유지하기

주기적으로 Qiskit 릴리스 노트와 Qiskit Runtime 릴리스 노트를 확인하여 새 릴리스를 확인하세요. 예를 들어 requirements.txt의 버전을 최신 버전으로 변경한 다음 pip install -r requirements.txt 또는 의존성 관리 워크플로우에 맞는 명령을 실행하는 방식으로 qiskit 및 qiskit-ibm-runtime 요구 사항을 자주 업데이트하는 것을 권장합니다.

Need help? Try asking Qiskit Code Assistant.

문제 해결

Jupyter Notebook에서 "No Module 'qiskit'" 오류가 발생하는 경우

pip install qiskit을 사용하고 Anaconda에서 가상 환경을 설정한 경우, Jupyter Notebook에서 튜토리얼을 실행할 때 No Module 'qiskit' 오류가 발생할 수 있습니다. Qiskit을 설치하지 않았거나 가상 환경을 설정하지 않은 경우 설치 단계를 따르세요.

이 오류는 Qiskit이 설치되지 않은 환경에서 Qiskit 패키지를 임포트하려고 할 때 발생합니다. Anaconda-Navigator에서 Jupyter Notebook을 실행한 경우, Jupyter Notebook이 가상 환경 대신 기본(루트) 환경에서 실행되고 있을 가능성이 있습니다. Anaconda-Navigator의 Applications on 드롭다운 메뉴에서 가상 환경을 선택하세요. 이 메뉴에서 Anaconda 내의 모든 가상 환경을 확인할 수 있으며, Qiskit이 설치된 환경을 선택하여 Jupyter Notebook을 실행할 수 있습니다.

설치 중 컴파일 오류가 발생하는 경우

Qiskit은 여러 오픈 소스 Python 패키지에 의존하며, pip install qiskit을 실행할 때 이러한 패키지들이 자동으로 설치됩니다. 시스템의 플랫폼과 Python 버전에 따라 특정 패키지가 해당 시스템용 미리 빌드된 바이너리를 제공하지 않을 수 있습니다. Qiskit에서 지원하는 플랫폼 목록은 운영 체제 지원을 참고하세요. 일부 플랫폼에는 추가 컴파일러가 필요할 수 있습니다. 미리 컴파일된 바이너리가 없는 경우 pip은 소스에서 패키지를 컴파일하려고 시도하며, 이 경우 수동으로 설치해야 하는 추가 의존성이 필요할 수 있습니다.

pip install qiskit의 출력에 다음과 유사한 줄이 포함된 경우:

Failed building wheel for SOME_PACKAGE
...
build/temp.linux-x86_64-3.5/_openssl.c:498:30: fatal error
compilation terminated.
error: command 'x86_64-linux-gnu-gcc' failed with exit status 1

설치에 실패한 패키지(예시 코드에서는 SOME_PACKAGE)의 문서에서 소스에서 컴파일하는 데 필요한 라이브러리를 설치하는 방법에 대한 정보를 확인하세요.

운영 체제 지원

Qiskit은 가능한 한 많은 운영 체제를 지원하기 위해 노력하지만, 사용 가능한 테스트 리소스와 운영 체제 가용성의 한계로 인해 모든 운영 체제를 지원할 수는 없습니다. Qiskit의 운영 체제 지원은 각각 다른 수준의 지원을 제공하는 세 가지 등급으로 나뉩니다. FreeBSD나 WebAssembly(WASI)와 같이 이 범주에 속하지 않는 플랫폼에서도 Qiskit을 설치할 수 있을 수 있지만, 테스트되지 않았으며 소스에서 Qiskit(및 Qiskit의 의존성)을 빌드해야 합니다.

또한 Qiskit은 Python 언어의 CPython 구현만 지원합니다. PyPy와 같은 다른 Python 인터프리터로의 실행은 지원되지 않습니다.

Qiskit v2.x

Qiskit v2.x 릴리스 시리즈에서 지원되는 플랫폼은 다음과 같습니다:

1등급

1등급 운영 체제는 제안된 변경 사항이 올바르게 작동하는지 확인하기 위해 개발 프로세스의 일환으로 완전히 테스트됩니다. 미리 컴파일된 바이너리가 릴리스 프로세스의 일환으로 빌드, 테스트되고 PyPI에 게시됩니다. 일반적으로 Python 환경이 제대로 설치되어 있는 한, 추가 의존성을 설치하지 않고도 이러한 운영 체제에 Qiskit을 설치할 수 있습니다.

1등급 운영 체제:

Linux x86_64(manylinux 2014 패키징 사양과 호환되는 배포판)
macOS ARM64(11.0 이상)
Windows 64비트(Windows 10 이상 지원)
Linux AArch64(manylinux 2014 패키징 사양과 호환되는 배포판)

2등급

2등급 운영 체제는 개발 프로세스의 일환으로 테스트되지 않습니다. 하지만 미리 컴파일된 바이너리가 릴리스 프로세스의 일환으로 빌드, 테스트되고 PyPI에 게시되므로, 이러한 패키지는 Python 환경만 있으면 설치할 수 있을 것으로 기대할 수 있습니다. 테스트 실패가 훨씬 늦게 감지될 수 있고, 게시 중 실패가 1등급 시스템용 패키지 게시를 차단하지 않으므로 이러한 시스템용 패키지 릴리스가 지연될 수 있습니다.

2등급 운영 체제:

macOS x86_64(10.12 이상)

3등급

3등급 운영 체제는 개발 프로세스의 일환으로 테스트되지 않습니다. 미리 컴파일된 바이너리가 릴리스 프로세스의 일환으로 빌드되고 PyPI에 게시되지만 테스트되지 않습니다. Python 환경만으로는 설치할 수 없을 수 있으며, 설치 프로세스의 일환으로 소스에서 의존성을 빌드하기 위해 C/C++ 컴파일러나 추가 프로그램이 필요할 수 있습니다. 이러한 운영 체제에 대한 지원은 최선의 노력을 기반으로 합니다.

3등급 운영 체제:

Linux ppc64le(manylinux 2014패키징 사양과 호환되는 배포판)
Linux s390x(manylinux 2014 패키징 사양과 호환되는 배포판)

Qiskit v2.0.0부터는 64비트 플랫폼만 지원하며 32비트 플랫폼은 지원되지 않습니다. 내부적으로 Qiskit Rust 코드가 64비트 포인터 너비를 가정하므로 32비트 플랫폼에서는 소스에서 빌드할 수도 없습니다.

Qiskit v1.x

Qiskit v1.x 릴리스 시리즈에서 지원되는 플랫폼은 다음과 같습니다:

1등급

1등급 운영 체제:

Linux x86_64(manylinux 2014 패키징 사양과 호환되는 배포판)
macOS x86_64(10.12 이상)
macOS ARM64(11.0 이상)
Windows 64비트(Windows 10 이상 지원)

2등급

2등급 운영 체제는 개발 프로세스의 일환으로 테스트되지 않습니다. 하지만 미리 컴파일된 바이너리가 릴리스 프로세스의 일환으로 빌드, 테스트되고 PyPI에 게시되므로, 이러한 패키지는 Python 환경만 있으면 설치할 수 있을 것으로 기대할 수 있습니다.

2등급 운영 체제:

Linux AArch64(manylinux 2014 패키징 사양과 호환되는 배포판)

3등급

3등급 운영 체제:

Linux ppc64le(manylinux 2014패키징 사양과 호환되는 배포판)
Linux s390x(manylinux 2014 패키징 사양과 호환되는 배포판)
Linux i686(manylinux 2014 패키징 사양과 호환되는 배포판)
Windows 10 32비트

다음 단계

권장 사항

IBM Cloud 계정을 설정하세요.
로컬에서 Qiskit을 구성하세요.
Hello world의 단계를 따라 양자 프로그램을 작성하고 실행해 보세요.
IBM Quantum Learning 튜토리얼을 시도해 보세요.

Qiskit SDK와 Qiskit Runtime 클라이언트 설치​

문제 해결​

운영 체제 지원​

Qiskit v2.x​

Qiskit v1.x​

다음 단계​