Qiskit은 설치했는데 VS Code나 Jupyter에서 찾지 못한다면 실행 환경부터 확인해야 합니다. Windows의 기존 .venv를 편집기와 노트북에 연결하고, 같은 Python으로 실행되는지 확인하는 방법을 정리했습니다.
1. Qiskit 설치를 마친 프로젝트 폴더 열기
이 글은 Windows Qiskit 설치와 첫 회로 실행을 마쳐 프로젝트 폴더 안에 .venv가 있는 상태에서 시작합니다. 아직 설치하지 않았다면 연결된 글부터 진행하세요.
탐색기에서 실제 qiskit-practice 폴더를 찾습니다. VS Code의 File → Open Folder로 이 폴더를 열고 Terminal → New Terminal을 선택합니다. 아래 명령은 PowerShell 터미널 기준입니다.
pwd
dir -Force
.\.venv\Scripts\python.exe -c "import sys; print(sys.executable)"마지막 명령의 경로가 현재 프로젝트의 .venv\Scripts\python.exe로 끝나야 합니다. 경로를 찾을 수 없다면 폴더 위치와 .venv 존재 여부부터 확인하세요. 여기서는 Python 실행 파일을 직접 지정하므로 가상환경 활성화 스크립트를 실행할 필요가 없습니다.
2. VS Code에 Python 확장과 인터프리터 연결하기
VS Code 공식 사이트에서 편집기를 설치합니다. Extensions 화면에서 게시자가 Microsoft인 Python과 Jupyter 확장을 설치하세요.
Ctrl+Shift+P → Python: Select Interpreter를 실행하고 프로젝트의 .venv를 선택합니다. 목록에 없다면 Enter interpreter path에서 .venv\Scripts\python.exe를 지정합니다.
프로젝트에 check_environment.py를 만들고 아래 코드를 저장한 뒤 Run Python File in Terminal로 실행합니다. 일반 Code Runner 확장의 실행 버튼은 다른 Python을 사용할 수 있으므로 구분하세요.
import sys
import qiskit
print(sys.executable)
print(qiskit.__version__)3. Jupyter 커널 등록하기
같은 프로젝트의 PowerShell 터미널에서 다음 명령을 차례로 실행합니다. ipykernel은 현재 가상환경을 노트북의 Python 실행 환경으로 연결합니다.
.\.venv\Scripts\python.exe -m pip install ipykernel
.\.venv\Scripts\python.exe -m ipykernel install --user --name qiskit-practice --display-name "Python (qiskit-practice)"여러 프로젝트를 운영한다면 --name과 표시 이름을 프로젝트마다 다르게 정하세요. 같은 이름으로 다시 등록하면 기존 커널 정보가 갱신될 수 있습니다.
4. 노트북에서도 같은 Python인지 확인하기
VS Code에서 practice.ipynb 파일을 만들고 오른쪽 위 Select Kernel에서 방금 등록한 Python (qiskit-practice) 또는 해당 .venv 환경을 선택합니다. 커널 목록이 늦게 갱신되면 노트북을 다시 열어 확인합니다.
import sys
import qiskit
print(sys.executable)
print(qiskit.__version__)출력 경로가 2단계의 .py 파일에서 확인한 경로와 같으면 두 환경이 연결된 것입니다. 코드 입력란이 Markdown 셀로 되어 있다면 Code 셀로 바꾼 뒤 실행하세요.
5. 첫 회로를 노트북 셀에서 확인하기
from qiskit import QuantumCircuit
circuit = QuantumCircuit(1, 1)
circuit.h(0)
circuit.measure(0, 0)
print(circuit.draw(output="text"))이 코드는 회로를 만들고 문자로 표시합니다. 실제 양자컴퓨터에 작업을 전송하거나 측정 횟수를 집계하는 코드는 아닙니다. 로컬 측정 실습은 Qiskit Aer 실행 안내로 이어가세요.
6. 설치는 됐는데 실행되지 않을 때
No module named qiskit: 오류가 난 .py 파일이나 노트북에서 sys.executable을 먼저 확인하세요. 터미널의 Python과 노트북 커널이 다르면 한쪽에 설치한 패키지를 다른 쪽에서 찾지 못합니다.
qiskit.py 이름 충돌: 직접 만든 파일 이름이 qiskit.py라면 practice_circuit.py처럼 바꾸고 커널을 재시작하세요. 프로젝트 안의 같은 이름 폴더도 확인합니다.
예전 변수나 결과가 남는 문제: 커널을 재시작한 다음 위에서 아래로 셀 전체를 다시 실행합니다. 결과를 비교할 때는 셀 실행 순서도 함께 확인하세요.
PowerShell 활성화 오류: 이 글의 .\.venv\Scripts\python.exe 명령처럼 Python 경로를 직접 지정하면 활성화 스크립트 없이 해당 환경을 사용할 수 있습니다.
7. 재현할 수 있도록 버전과 결과 기록하기
.\.venv\Scripts\python.exe -m pip freeze > requirements.txtrequirements.txt는 설치 패키지 버전을 기록합니다. Python 버전, 운영체제, 실행 날짜와 실제 결과도 함께 남기세요. 이 파일만으로 다른 운영체제에서의 완전한 재현이 보장되지는 않습니다.
실습 기록에는 본인이 실행해 얻은 경로·버전·출력 화면을 사용하세요. 여기의 명령과 코드에는 특정 사용자의 실행 결과나 실제 QPU 측정 결과를 넣지 않았습니다.
공식 참고문헌
Microsoft — Python environments in VS Code