Jupyter Notebook은 Qiskit 코드를 파일로 매번 실행하지 않고 한 단계씩 확인하고 싶을 때 편리한 도구입니다. 윈도우에서 전용 가상환경을 만들고 Jupyter와 Qiskit을 연결한 뒤 첫 실험까지 직접 실행해봅니다.
양자컴퓨팅 실험을 하다 보면 코드를 한 번에 실행하기보다 회로를 만들고, 결과를 확인하고, 그래프를 그리는 과정을 단계별로 나눠보고 싶을 때가 많습니다. Jupyter Notebook은 이런 작업에 잘 맞는 개발환경입니다.
Python 코드를 셀 단위로 실행할 수 있고 바로 아래에서 결과를 확인할 수 있으며, 설명문과 그래프까지 하나의 파일에 함께 저장할 수 있습니다. 이번 글에서는 Windows PC를 기준으로 Jupyter Notebook을 설치하고 기존 Qiskit 환경과 연결한 뒤 Bell State 양자회로를 직접 실행해봅니다.
1. Jupyter Notebook은 일반 코드 편집기와 무엇이 다를까?
일반적인 Python 파일은 여러 줄의 코드를 작성한 뒤 파일 전체를 실행하는 방식이 익숙합니다. 반면 Jupyter Notebook에서는 하나의 문서를 여러 개의 셀(Cell)로 나누어 필요한 부분만 실행할 수 있습니다.
| 항목 | 일반 Python 파일 | Jupyter Notebook |
|---|---|---|
| 실행 방식 | 파일 전체 실행 중심 | 셀 단위 실행 |
| 결과 확인 | 터미널 출력 | 코드 바로 아래 출력 |
| 그래프 | 별도 창 또는 출력 | Notebook 안에서 바로 표시 |
| 설명 작성 | 주석 중심 | Markdown 셀 사용 |
| 실험 기록 | 코드와 설명 분리 | 코드·설명·결과를 한 파일에 저장 |
| 파일 형식 | .py | .ipynb |
특히 양자컴퓨팅에서는 회로를 만든 뒤 회로 구조를 확인하고, shots를 바꾸고, 결과 분포를 비교하는 작업을 반복하게 됩니다. 이 과정을 각각의 셀로 나누면 실험 흐름을 이해하기 쉬워집니다.
2. Notebook의 핵심은 셀과 Kernel이다
Jupyter Notebook을 이해할 때 두 가지만 먼저 알아두면 됩니다.
- Cell: 코드나 설명을 입력하는 각각의 영역
- Kernel: 셀에 입력한 Python 코드를 실제로 실행하는 프로세스
코드 셀에서 Shift + Enter를 누르면 해당 코드가 Kernel로 전달되고 실행 결과가 바로 아래에 표시됩니다. Markdown 셀에는 실험 목적이나 결과 해석을 일반 문장으로 작성할 수 있습니다.
따라서 Notebook 파일 자체에 Qiskit이 들어 있는 것이 아니라, Notebook이 어떤 Python Kernel과 연결되어 있는지가 중요합니다. Qiskit을 설치하지 않은 Python 환경을 Kernel로 선택하면 No module named qiskit 오류가 발생할 수 있습니다.
3. 이번에 만들 양자컴퓨팅 실험환경
이번 글에서는 다른 Python 프로젝트와 패키지가 섞이지 않도록 별도의 가상환경을 만든 뒤 그 안에 Qiskit과 Jupyter Notebook을 함께 설치합니다.
Windows
↓
qiskit-practice 폴더
↓
.venv 가상환경
├─ Qiskit
├─ Jupyter Notebook
├─ IPython Kernel
└─ Matplotlib
↓
양자실험.ipynb
이미 앞선 Qiskit 설치 글에서 만든 qiskit-practice 가상환경이 있다면 새로 만들지 않고 기존 환경에 Jupyter만 추가해도 됩니다.
4. Windows에서 작업폴더와 가상환경 만들기
먼저 Python이 설치되어 있어야 합니다. 아직 설치하지 않았다면 Windows Python·Qiskit 설치 안내의 준비 과정을 진행하세요. PowerShell에서 python --version으로 버전이 표시되는지 확인한 뒤 실습용 폴더를 만듭니다. 기존 qiskit-practice 폴더와 가상환경이 있다면 해당 폴더로 이동해 활성화하는 단계부터 진행하세요.
mkdir qiskit-practice
cd qiskit-practice이제 Python 가상환경을 생성합니다.
python -m venv .venvPowerShell에서는 아래 명령으로 활성화합니다.
.venv\Scripts\Activate.ps1명령창 앞부분에 (.venv)가 표시되면 정상적으로 활성화된 것입니다.
PowerShell의 실행정책 때문에 활성화되지 않는 경우 Command Prompt에서 다음 명령을 사용할 수도 있습니다.
.venv\Scripts\activate.bat5. Jupyter Notebook과 Qiskit 설치하기
가상환경이 활성화된 상태에서 pip를 먼저 업데이트합니다.
python -m pip install --upgrade pip이제 Notebook, Qiskit, IPython Kernel과 시각화 패키지를 함께 설치합니다.
python -m pip install notebook ipykernel "qiskit[visualization]" matplotlibProject Jupyter 공식 설치 페이지에서도 Jupyter Notebook은 pip install notebook으로 설치하고 jupyter notebook으로 실행하는 방식을 안내하고 있습니다.
6. Qiskit 전용 Kernel 등록하기
한 PC에 Python 환경이 여러 개 있다면 Notebook이 엉뚱한 Python을 선택할 수 있습니다. 이를 방지하려면 현재 가상환경을 Qiskit 전용 Kernel로 등록해두는 것이 편리합니다.
python -m ipykernel install --user --name qiskit-practice --display-name "Python (Qiskit Practice)"--name은 Jupyter가 내부적으로 사용하는 이름이고, --display-name은 Notebook 화면에서 실제로 보이는 Kernel 이름입니다.
앞으로 Notebook을 열었을 때 Python (Qiskit Practice)를 선택하면 방금 Qiskit을 설치한 가상환경에서 코드를 실행할 수 있습니다.
7. Jupyter Notebook 실행하기
설치가 끝났다면 PowerShell에서 다음 명령을 입력합니다.
jupyter notebook잠시 기다리면 기본 웹브라우저에서 Notebook Dashboard가 열립니다. 별도의 인터넷 사이트에 접속한 것처럼 보이지만 실제 계산은 현재 PC에서 실행되고 있습니다.
- Notebook Dashboard가 열리는지 확인
- New Notebook 생성
- Kernel을 Python (Qiskit Practice)로 선택
- 파일 이름을 first-quantum-experiment.ipynb 등으로 변경
터미널을 종료하면 Notebook 서버도 함께 종료될 수 있으므로 실습 중에는 Jupyter를 실행한 터미널을 그대로 두는 것이 좋습니다.
8. Notebook이 정말 Qiskit 환경을 사용하고 있는지 확인하기
첫 번째 코드 셀에서 Python과 Qiskit의 위치를 확인해봅니다.
import sys
import qiskit
print("Python:", sys.executable)
print("Qiskit:", qiskit.__version__)
Python 경로에 현재 만든 .venv 폴더가 포함되어 있고 Qiskit 버전이 정상적으로 출력된다면 개발환경 연결이 완료된 것입니다.
9. 셀을 나눠 Bell State 실험해보기
Notebook의 장점이 가장 잘 드러나는 방식으로 하나의 실험을 여러 단계로 나누어 실행해보겠습니다.
셀 1 — 필요한 도구 불러오기
이번 실습은 StatevectorSampler로 양자회로를 시뮬레이션합니다. 계산은 현재 PC에서 이루어지며, IBM 실제 양자컴퓨터(QPU)를 사용하지 않습니다. IBM 계정이나 API 키도 필요하지 않습니다.
from qiskit import QuantumCircuit
from qiskit.primitives import StatevectorSampler
from qiskit.visualization import plot_histogram셀 2 — Bell State 회로 만들기
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()
qc.draw("mpl")셀을 실행하면 코드 바로 아래에 Hadamard 게이트와 CNOT 게이트가 포함된 양자회로가 표시됩니다.
셀 3 — 1,024번 측정하기
sampler = StatevectorSampler()
result = sampler.run(
[qc],
shots=1024
).result()
counts = result[0].data.meas.get_counts()
print(counts)정상적으로 실행됐다면 00과 11이 주로 측정됩니다. 각각의 횟수는 실행할 때마다 조금씩 달라질 수 있습니다.
셀 4 — 결과를 그래프로 확인하기
plot_histogram(counts)이렇게 하면 회로 코드, 측정값, 그래프를 모두 하나의 Notebook 안에서 순서대로 확인할 수 있습니다.
10. Notebook을 실험노트처럼 사용하는 방법
Notebook의 가장 큰 장점은 단순히 Python을 실행할 수 있다는 것이 아닙니다. 코드 사이에 Markdown 셀을 추가해 실험 조건과 결과 해석을 함께 기록할 수 있습니다.
# 실험 제목 Bell State 1,024회 측정 ## 실험 조건 - 큐비트: 2개 - shots: 1024 - H gate: q0 - CNOT: q0 → q1 ## 예상 00과 11이 약 50%씩 측정될 것으로 예상 ## 실제 결과 실행 결과를 확인한 뒤 기록 ## 해석 00과 11의 비율 차이를 확인
이렇게 작성하면 하나의 .ipynb 파일이 코드 파일이면서 동시에 실험기록이 됩니다. shots만 바꾸거나 노이즈 모델을 추가하면서 결과를 아래쪽에 계속 기록하기에도 좋습니다.
11. 자주 발생하는 오류
No module named qiskit
가장 먼저 현재 Notebook의 Kernel을 확인합니다. Qiskit을 설치한 가상환경과 Notebook의 Kernel이 서로 다르면 이 오류가 발생할 수 있습니다.
Notebook 셀에서 다음 코드를 실행하면 현재 사용하는 Python 위치를 확인할 수 있습니다.
import sys
print(sys.executable)jupyter 명령을 찾을 수 없다
가상환경이 활성화됐는지 확인하고 같은 환경에서 Notebook을 설치했는지 확인합니다.
python -m pip show notebook회로 그림이 나오지 않는다
시각화 관련 패키지가 빠져 있을 수 있습니다.
python -m pip install "qiskit[visualization]" matplotlib12. Google Colab과 Jupyter Notebook 중 무엇을 쓸까?
| 상황 | 추천 |
|---|---|
| 설치 없이 바로 시작하고 싶음 | Google Colab |
| 내 PC에서 파일을 장기간 관리 | Jupyter Notebook |
| Qiskit 가상환경을 직접 관리 | Jupyter Notebook |
| 다른 PC에서도 쉽게 실행 | Google Colab |
| 실험 결과를 .ipynb로 계속 축적 | Jupyter Notebook |
| 처음 10분 정도만 체험 | Google Colab |
두 도구가 경쟁 관계인 것은 아닙니다. Google Colab 역시 Notebook 방식의 인터페이스를 사용합니다. Colab은 실행환경을 Google이 제공하는 방식이고, Jupyter Notebook은 자신의 PC에서 직접 Python 환경과 패키지를 관리한다는 차이가 있습니다.
13. 다음에는 무엇을 해볼까?
Jupyter Notebook 환경까지 준비했다면 앞으로 이 블로그의 Qiskit 실험을 하나의 실험노트로 모아볼 수 있습니다. 먼저 shots를 100회, 1,000회, 10,000회로 바꿔 결과가 어떻게 달라지는지 확인해보는 방법이 좋습니다.
- Hadamard 게이트로 동전 던지기 실험
- Bell State 반복 측정
- Qiskit Aer 노이즈 모델 실험
- T1·T2 상태 변화 실험
- 시뮬레이터와 실제 QPU 결과 비교
실제 IBM Quantum 하드웨어를 사용할 계획이라면 같은 가상환경에 qiskit-ibm-runtime을 추가해 실제 QPU 실험으로 확장할 수도 있습니다.
python -m pip install qiskit-ibm-runtimePC 설치나 가상환경 연결이 어렵다면 Google Colab에서 Qiskit 시작하기를 이용하세요. 같은 Bell State 회로를 브라우저에서 실습할 수 있습니다.
관련 글
- Qiskit 설치 방법 2026｜무료로 양자컴퓨터 회로 만들고 첫 실행까지 따라하기
- Qiskit Aer란? 실제 양자컴퓨터 없이 무료로 양자회로 실행·노이즈 실험하는 방법
- 양자컴퓨터도 시간이 지나면 기억을 잃을까? T1 노이즈 직접 실험
- 양자컴퓨터 1,000번 실행하면 매번 50:50일까? 실제 QPU 반복실험