오늘은 AI 관련하여 최근 Python을 다루는 분들이 많아지는 것 같아, 본격적인 AI 연동 개발 전 Python 개발 환경에 대해 몇가지 다뤄보려고 한다. 그 중 오늘은 로컬 환경 세팅 관련하여 첫번째글에 이어 2번째 과정으로 Jupyter Notebook에 대해 다뤄볼 예정이다.
파이썬 로컬 개발환경의 확장 - 탐색 도구 Jupyter Notebook Python 개발환경(venv, uv)을 구축한 후, 코드 실험과 데이터 탐색을 위한 인터랙티브 도구인 Jupyter Notebook을 추가하는 방법을 다루려고 한다. 설치부터 하이브리드 워크플로우까지, 실무에서 활용 가능한 가이드이다.
파이썬 개발환경을 구축했다면, 이제 개발 워크플로우를 완성할 차례다. 가상환경 설정, 패키지 관리자 구성까지 마쳤지만, 아직 빠진 퍼즐 조각이 있다. 바로 탐색과 실험을 위한 도구이다.
새로운 API를 연동할 때, 응답 구조를 확인하고 싶을 때가 있다. 데이터를 처리하면서 중간 결과를 시각화하고 싶을 때도 있다. 이런 상황에서 매번 Python 파일을 만들고, 실행하고, 결과를 확인하는 과정은 비효율적이다.
Jupyter Notebook은 이러한 탐색 작업에 최적화된 도구다. 이 글에서는 기존 개발환경에 Jupyter를 추가하고, Python 파일 기반 개발과 함께 사용하는 하이브리드 워크플로우를 소개해보려 한다.
Jupyter Notebook이란?
Jupyter Notebook은 코드, 텍스트, 시각화를 하나의 문서로 통합한 인터랙티브 개발 환경이다.
Project Jupyter에서 개발하며, 데이터 과학, 기계 학습, 교육 분야에서 널리 사용된다.
공식 문서 출처 "The Jupyter Notebook is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations and narrative text." "Jupyter Notebook은 오픈 소스 웹 애플리케이션으로, 실행 가능한 코드(live code), 수식(equations), 시각화(visualizations), 그리고 서술형 텍스트(narrative text)를 포함한 문서를 생성하고 공유할 수 있게 해줍니다." Jupyter 공식 사이트
핵심 특징
인터랙티브 실행: 코드 블록(셀) 단위로 실행하고 즉시 결과 확인 가능
시각화 통합: 그래프, 이미지, 표를 코드 바로 아래에 인라인으로 표시
문서화: Markdown과 코드를 섞어서 스토리텔링 방식의 설명 가능
탐색 도구: API 응답, 데이터 구조를 빠르게 실험하고 확인 가능
개발 환경에서의 역할
Jupyter Notebook은 최종 코드 작성 도구가 아니다. 탐색과 실험을 위한 보조 도구로 활용하는 것이 권장된다.
최종 프로덕션 코드는 Python 파일(.py)로 작성하고, pytest로 검증하는 것이 표준 워크플로우이다.
도구
역할
사용 시점
Python 파일 (.py)
최종 구현 및 배포
항상 (필수)
Jupyter Notebook (.ipynb)
실험 및 탐색
API 테스트, 데이터 분석 시 (보조)
pytest
테스트 및 검증
항상 (필수)
설치 및 환경 구성
1. uv로 Jupyter 설치
uv 패키지 관리자를 사용하면 Jupyter를 개발 의존성으로 추가할 수 있다. 프로젝트 의존성과 분리하여 관리하는 것이 권장된다.
# 개발 의존성으로 Jupyter 추가
uv add --dev jupyter
# 설치 확인
uv run jupyter --version
Jupyter를 실행하는 방법은 크게 세 가지가 있다. 각 방법의 특징을 이해하고 상황에 맞게 선택하자.
방법 1: VS Code 확장
위에서 설치한 VS Code Jupyter 확장을 사용하는 방법이다. IDE와 통합되어 가장 편리하다.
장점: Git 연동, 변수 탐색기, 셀 디버깅, 인텔리센스
단점: 확장 설치 필요, VS Code에 종속
추천: 일반적인 개발 작업, Python 프로젝트와 함께 사용 시
ex) VS Code 확장 프로그램 Jupyter 플러그인 설치 후 다음과 같이 보이는것을 확인할 수 있따.
방법 2: 브라우저 웹 인터페이스
터미널에서 직접 Jupyter 서버를 실행하고 브라우저에서 접속하는 전통적인 방법이다.
# 브라우저에서 Jupyter Notebook 실행
uv run jupyter notebook
# 실행되면 브라우저가 자동으로 열린다
# 기본 주소: http://localhost:8888
장점: 가볍고 빠름, 추가 설치 없음, 어디서나 동일한 인터페이스
단점: 별도 브라우저 탭 필요, Git 연동 없음
추천: 빠른 실험, VS Code 없는 환경, 원격 서버 접속 시
⚠️ 종료 방법 터미널에서 Ctrl+C를 두 번 눌러 Jupyter 서버를 종료할 수 있다.
ex) 다음과 같은 화면이 뜨면 example.ipynb 파일을 클릭하여 실행해보자.
- 다음과 같이 VS 확장 프로그램하고 거의 유사한 UI의 페이지가 뜨는걸 볼 수 있다.
방법 3: JupyterLab (고급)
JupyterLab은 차세대 Jupyter 인터페이스로, IDE 스타일의 통합 환경을 제공한다.
# JupyterLab 실행
uv run jupyter lab
# 기본 주소: http://localhost:8888/lab
장점: 파일 탐색기, 터미널, 여러 노트북 탭, 확장 시스템
단점: 리소스 더 사용, 학습 곡선
추천: 데이터 과학 집중 작업, 복잡한 분석 프로젝트
ex) 상기 브라우저 웹 인터페이스와 조금 다른 화면이 뜨고, example.ipynb 파일을 클릭하여 실행해보자.
- 다음과 같이 VS 확장 프로그램하고 거의 유사한 UI의 페이지가 뜨는걸 볼 수 있다.
실행 방법 비교표
항목
VS Code 확장
웹 (notebook)
JupyterLab
실행 명령어
.ipynb 파일 열기
jupyter notebook
jupyter lab
인터페이스
IDE 통합
단일 문서
IDE 스타일
Git 연동
✅ 내장
없음
⚠️ 확장 필요
변수 탐색기
✅ 내장
없음
✅ 내장
추천 용도
일반 개발
빠른 실험
데이터 과학
💡 선택 가이드 • Python 프로젝트와 함께: VS Code 확장 (Git, 디버깅, 인텔리센스 활용) • 가볍게 실험만: 웹 인터페이스 (jupyter notebook) • 데이터 분석 집중: JupyterLab (jupyter lab)
기본 사용법
노트북 파일 생성
VS Code에서 노트북 파일을 생성하는 방법은 두 가지다.
방법 1. 명령 팔레트: Cmd+Shift+P (Mac) 또는 Ctrl+Shift+P (Windows) → "Jupyter: Create New Blank Notebook" 검색
방법 2.파일 탐색기: 우클릭 → New File → 파일명을 example.ipynb로 지정
셀 종류
Jupyter 노트북은 두 가지 종류의 셀로 구성된다.
코드 셀: Python 코드를 작성하고 실행하는 셀
Markdown 셀: 제목, 설명, 문서를 작성하는 셀
ex) 블로그 작성을 위해 간단하게 샘플을 하나 작성해 보았다.
# 코드 셀 예시
# Jupyter Notebook 기초 실습
이 노트북은 Jupyter Notebook의 기본 사용법을 익히기 위한 예제입니다.
## 학습 내용
1. Markdown 셀 사용하기
2. 코드 셀 실행하기
3. Python 모듈 import하기
4. 하이브리드 워크플로우 체험하기
## 1. 기본 연산
# 간단한 계산
numbers = [1, 2, 3, 4, 5]
total = sum(numbers)
print(f"합계: {total}")
print(f"평균: {total / len(numbers)}")
## 2. 리스트 처리
리스트 컴프리헨션을 사용하여 데이터를 변환할 수 있습니다.
# 리스트 컴프리헨션
squared = [x**2 for x in numbers]
print(f"제곱 값: {squared}")
# 필터링
even_numbers = [x for x in numbers if x % 2 == 0]
print(f"짝수만: {even_numbers}")
## 3. Python 모듈 사용하기
같은 디렉토리의 `jupyter_setup.py`에서 함수를 import하여 사용합니다.
# jupyter_setup.py에서 함수 import
from jupyter_setup import greet, calculate_average
# greet 함수 사용
message = greet("AI 개발자")
print(message)
# calculate_average 함수 사용
test_numbers = [10, 20, 30, 40, 50]
avg = calculate_average(test_numbers)
print(f"평균: {avg}")
## 4. 에러 처리 연습
빈 리스트의 평균을 계산하려고 하면 어떻게 될까요?
# 에러 처리 예제
try:
empty_list = []
avg = calculate_average(empty_list)
print(f"평균: {avg}")
except ValueError as e:
print(f"에러 발생: {e}")
print("빈 리스트는 평균을 계산할 수 없습니다!")
ex) 단순히 소스로 보이는 저 부분을 Jupeter Note Book에서 보면 이런 형식으로 보인다.
ex) 빈 파일에서 다음과 같이 Markdown을 클릭해보자.
- 하기 내용 처럼 작성 하고 "Stop Editing Cell"을 클릭해 보자.
# Jupyter Notebook 기초 실습
이 노트북은 Jupyter Notebook의 기본 사용법을 익히기 위한 예제입니다.
## 학습 내용
1. Markdown 셀 사용하기
2. 코드 셀 실행하기
3. Python 모듈 import하기
4. 하이브리드 워크플로우 체험하기
- 한번 더 "+ Markdown > 하기 내용 작성 > Stop Editing Cell
## 1. 기본 연산
- 상기 2 stpe을 진행했다면 다음과 같이 보일 것 이다.
- 이제 코드 셀을 추가하고, 다음내용을 추가 해보자.
# 간단한 계산
numbers = [1, 2, 3, 4, 5]
total = sum(numbers)
print(f"합계: {total}")
print(f"평균: {total / len(numbers)}")
- 다음과 같이 버튼을 클릭하여 실행해보자.
- Python Environments > 로컬에 설치된 Python 환경 선택 ( 좀더 자세한 내용은 하기 [커널(Kernel) 선택하기] 섹션에서 설명 하도록 하겠다. )
- 바로 수행되며 수행된 시간, 콘솔등을 확인 할 수 있따.
주요 단축키
Jupyter 노트북에는 Edit Mode(셀 내용 편집)와 Command Mode(셀 조작)가 있다. Esc로 Command Mode, Enter로 Edit Mode로 전환한다.
단축키
기능
모드
Shift+Enter
셀 실행 및 다음 셀로 이동
Both
Ctrl+Enter
셀 실행 (이동 안 함)
Both
Alt+Enter (Mac: Option)
셀 실행 + 아래에 새 셀 추가
Both
A
위에 새 셀 추가
Command
B
아래에 새 셀 추가
Command
D D
셀 삭제
Command
Z
셀 삭제 취소 (Undo)
Command
M
Markdown 셀로 변환
Command
Y
코드 셀로 변환
Command
커널(Kernel) 선택하기
VS Code에서 노트북 셀을 처음 실행하면 "Select Kernel" 대화상자가 나타난다. 여기서 코드를 실행할 Python 환경을 선택해야 한다.
Select Kernel 옵션 설명
옵션
설명
사용 시점
Python Environments...
로컬 Python 환경 선택 (venv, .venv, conda, 시스템 Python)
대부분의 경우 이것 선택
Existing Jupyter Server...
원격 Jupyter 서버에 연결 (URL 입력 필요)
팀 서버, 클라우드 환경 연결 시
uv 프로젝트에서 커널 선택하기
uv로 프로젝트를 생성한 경우, .venv 폴더에 가상환경이 만들어진다. 다음 단계로 커널을 선택하자.
"Python Environments..." 클릭
목록에서 .venv 또는 프로젝트 이름이 포함된 환경 선택 • Mac/Linux: .venv/bin/python • Windows: .venv\Scripts\python.exe
선택 완료 후 셀 실행 (Shift+Enter)
# 올바른 커널인지 확인하는 방법 (노트북 셀에서 실행)
import sys
print(sys.executable)
# 출력 예: /프로젝트경로/.venv/bin/python
커널이 목록에 없다면? • uv sync 명령어로 가상환경이 생성되었는지 확인 • VS Code 창을 닫고 다시 열기 (새 Python 환경 감지) • Command Palette (Cmd+Shift+P) → "Python: Select Interpreter"로 직접 선택
"Existing Jupyter Server"는 언제 사용하나? • 팀에서 공유하는 원격 Jupyter 서버에 연결할 때 • AWS SageMaker, Google Cloud AI Platform 같은 클라우드 환경 • 로컬이 아닌 서버의 GPU를 사용해야 할 때 • 일반적인 로컬 개발에서는 사용하지 않는다
언제 Jupyter를 사용해야 할까?
Jupyter Notebook은 만능 도구가 아니다. 상황에 따라 적합한 도구를 선택하는 것이 효율적인 개발의 핵심이다.
Google Colab은 클라우드 기반 Jupyter 환경이다. 로컬 Jupyter와의 핵심 차이점을 이해하면 상황에 맞는 선택이 가능하다.
항목
로컬 Jupyter
Google Colab
세션 유지
무제한 (직접 종료 전까지)
최대 12시간 (유휴 90분 자동 종료)
GPU/TPU
로컬 하드웨어 의존
무료 GPU (사용량 제한)
환경 설정
직접 관리 (완전 제어)
런타임마다 재설치 필요
데이터 보안
로컬 저장 (외부 노출 없음)
Google 서버 저장
협업
Git 기반 공유
링크 공유, 실시간 협업
비용
무료 (로컬 PC 자원)
무료 / Pro 유료
오프라인
가능
불가능
선택 가이드
로컬 Jupyter 선택
민감한 데이터 처리
장시간 학습/실험
안정적인 환경 필요
오프라인 작업
Google Colab 선택
GPU가 필요한 ML 작업
빠른 시작, 설치 없이
팀원과 실시간 협업
일회성 실험/데모
세션 관리 팁 • Colab 유휴 종료 방지: 주기적으로 셀 실행하거나 브라우저 탭 활성 유지 • 로컬 Jupyter: "Kernel 재시작"과 "세션 종료"는 다름 — Kernel 재시작은 변수만 초기화
Jupyter 심화 이해
Jupyter를 효과적으로 사용하려면 내부 동작 원리를 이해하는 것이 도움이 된다.
Kernel (커널) 개념
Kernel은 코드를 실행하는 엔진이다. Python Jupyter의 경우 IPython 인터프리터 프로세스가 Kernel 역할을 한다.
노트북과 Kernel의 관계
┌─────────────────┐ ┌─────────────────┐
│ 노트북 파일 │ │ Kernel │
│ (.ipynb 문서) │ ←──→ │ (Python 프로세스) │
│ │ 코드 │ │
│ • 셀 내용 │ 전송 │ • 변수 저장 │
│ • Markdown │ ←──→ │ • import 상태 │
│ • 출력 결과 │ 결과 │ • 실행 컨텍스트 │
└─────────────────┘ └─────────────────┘
노트북 ≠ Kernel: 노트북 파일은 문서일 뿐, 실행은 Kernel이 담당
Kernel 재시작: 모든 변수, import, 실행 상태 초기화
독립 실행: 각 노트북은 별도의 Kernel을 가짐 (공유 불가)
.ipynb 파일 구조
노트북 파일은 JSON 형식이다. 이 구조를 알면 Git diff가 복잡해지는 이유를 이해할 수 있다.
# .ipynb 파일 구조 (JSON)
{
"nbformat": 4,
"nbformat_minor": 5,
"metadata": {
"kernelspec": {
"name": "python3",
"display_name": "Python 3"
}
},
"cells": [
{
"cell_type": "code",
"source": ["print('Hello')"],
"outputs": [...] ← 실행 결과 포함 (파일 크기 증가 원인)
}
]
}
⚠️ Git 관리 시 주의 outputs 필드에 실행 결과(텍스트, 이미지 base64 등)가 저장된다. 커밋 전 --clear-output으로 제거하면 diff가 깔끔해진다.
ex) 실행된 노트북 화면은 다음과 같지만
ex) git 변경 이력을 확인해보면 소스는 json구조이다.
Magic Commands
Jupyter는 Python 문법 외에 특수 명령어를 제공한다. %는 한 줄, %%는 셀 전체에 적용된다.
명령어
기능
사용 예시
%time
코드 실행 시간 측정 (1회)
%time sum(range(10000))
%timeit
평균 실행 시간 측정 (여러 번)
%timeit sorted(data)
%who
정의된 변수 목록 표시
%who str (문자열만)
%whos
변수 상세 정보 (이름, 타입, 값)
%whos
%%bash
셀 전체를 bash로 실행
%%bash ls -la
%load
외부 파일 코드 로드
%load utils.py
%%writefile
셀 내용을 파일로 저장
%%writefile utils.py
%load_ext
IPython 확장 로드
%load_ext autoreload
%pwd
현재 작업 디렉토리 출력
%pwd
%cd
디렉토리 변경
%cd .. 또는 %cd ~
%ls
디렉토리 내용 나열
%ls
%lsmagic
사용 가능한 모든 매직 명령어 표시
%lsmagic
%matplotlib inline
그래프를 셀 아래에 인라인 표시
%matplotlib inline
%autoreload
import된 모듈 자동 리로드
%autoreload 2
# Magic Command 활용 예시 (복사해서 바로 실행 가능)
# 테스트용 데이터 생성
import random
large_list = [random.randint(1, 1000) for _ in range(10000)]
# 실행 시간 비교 (sorted는 새 리스트 반환, .sort()는 원본 변경)
%timeit sorted(large_list)
%timeit large_list.copy().sort()
# 현재 정의된 변수 확인
%who
# 모든 magic 명령어 목록
%lsmagic
# 실행 결과 예시
833 µs ± 28.1 µs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)
833 µs ± 21.8 µs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)
large_list random
💡 결과 해석 • 833 µs ± 28.1 µs: 평균 833마이크로초(0.833ms), 표준편차 28.1µs • 7 runs, 1,000 loops each: 7번의 테스트, 각 테스트당 1,000회 반복 실행한 결과 • 두 방식(sorted()와 .copy().sort())의 성능이 거의 동일함을 확인할 수 있다 • %who 결과: 현재 정의된 변수 large_list, random 모듈 표시
개발자 필수 설정
개발자가 Jupyter를 효과적으로 사용하기 위해 알아야 할 필수 설정들이다.
1. autoreload - Python 파일 자동 반영
하이브리드 워크플로우의 핵심 기능이다. Python 파일을 수정하면 노트북에서 자동으로 반영된다.
Step 1: 먼저 테스트용 Python 파일을 생성한다. (아래 코드를 셀에서 실행)
# %%writefile 매직으로 Python 파일 자동 생성
%%writefile my_utils.py
def greet(name):
"""인사 메시지를 반환한다."""
return f"안녕하세요, {name}님!"
def add(a, b):
"""두 숫자를 더한다."""
return a + b
Step 2: autoreload 설정 후 import하여 사용한다.
# autoreload 활성화
%load_ext autoreload
%autoreload 2
# 방금 만든 모듈 import
from my_utils import greet, add
print(greet("개발자")) # 출력: 안녕하세요, 개발자님!
print(add(10, 20)) # 출력: 30
# 이제 my_utils.py를 수정하면 자동으로 반영된다!
# 예: greet 함수의 메시지를 바꾸고 다시 실행해보자
💡 autoreload 옵션 • %autoreload 0: 비활성화 • %autoreload 1: %aimport로 지정한 모듈만 자동 리로드 • %autoreload 2: 모든 모듈 자동 리로드 (권장)
2. matplotlib inline - 그래프 인라인 표시
matplotlib 그래프를 셀 아래에 바로 표시하는 설정이다. 먼저 matplotlib을 설치해야 한다.
# 터미널에서 matplotlib 설치 (노트북 실행 전)
# uv 사용 시
uv add matplotlib
# pip 사용 시
pip install matplotlib
설치 후 노트북에서 다음 코드를 실행한다.
%matplotlib inline
import matplotlib.pyplot as plt
import random
# 샘플 데이터 생성
x = list(range(1, 11))
y = [random.randint(1, 10) for _ in range(10)]
# 이제 그래프가 셀 아래에 표시된다
plt.figure(figsize=(8, 4))
plt.plot(x, y, marker='o', linestyle='-', color='#0066cc')
plt.title("랜덤 데이터 샘플 그래프")
plt.xlabel("X축")
plt.ylabel("Y축")
plt.grid(True, alpha=0.3)
plt.show()
⚠️ ModuleNotFoundError 발생 시 ModuleNotFoundError: No module named 'matplotlib' 오류가 나타나면 다음을 확인하자.
1. 설치 여부 확인 uv run python -c "import matplotlib; print(matplotlib.__version__)" 이 명령어가 오류 나면 matplotlib이 설치되지 않은 것이다.
2. 설치 후에도 오류가 계속된다면? • 커널 환경 확인: 노트북 셀에서 import sys; print(sys.executable) 실행 • 출력 경로가 .venv/bin/python이 아니면 커널이 잘못 선택된 것 • 노트북 우측 상단 커널 선택 → "Python Environments..." → .venv 환경 선택
3. 커널 재시작: 패키지 설치 후 반드시 커널을 재시작해야 새 패키지를 인식한다.
matplotlib 한글 폰트 설정
matplotlib은 기본적으로 한글을 지원하지 않아 "□□□"처럼 깨져 보인다. 다음 설정으로 해결할 수 있다.
import matplotlib.pyplot as plt
import platform
# 운영체제별 한글 폰트 설정
if platform.system() == 'Darwin': # macOS
plt.rcParams['font.family'] = 'AppleGothic'
elif platform.system() == 'Windows':
plt.rcParams['font.family'] = 'Malgun Gothic'
else: # Linux
plt.rcParams['font.family'] = 'NanumGothic'
# 마이너스 기호 깨짐 방지
plt.rcParams['axes.unicode_minus'] = False
print(f"✅ 한글 폰트 설정 완료: {plt.rcParams['font.family']}")
💡 팁 위 코드를 matplotlib을 import한 직후에 실행하면 된다. 노트북 시작 템플릿에 추가해두면 편리하다.
3. 환경 변수 로드 (API 키 관리)
API 키나 민감한 설정 값을 .env 파일에서 안전하게 로드한다.
# python-dotenv 설치 필요: uv add python-dotenv
from dotenv import load_dotenv
import os
# .env 파일 로드
load_dotenv()
# 환경 변수 사용
api_key = os.getenv("OPENAI_API_KEY")
print(f"API Key: {'설정됨 ✓' if api_key else '미설정 ✗'}")
⚠️ 주의 .env 파일은 절대 Git에 커밋하지 마라. .gitignore에 추가하고, .env.example 파일로 템플릿만 공유하자.
4. 작업 디렉토리 관리
노트북에서 파일을 읽거나 저장할 때 작업 디렉토리를 확인하고 변경하는 방법이다.
# 현재 디렉토리 확인
%pwd
# 디렉토리 내용 확인 (파일 목록)
%ls
# 상위 디렉토리로 이동
%cd ..
# 이전 디렉토리로 돌아가기
%cd -
# 홈 디렉토리로 이동
%cd ~
# 디렉토리 히스토리 확인 (이전에 방문한 경로들)
%dhist
💡 팁 VS Code에서 노트북을 열면 기본 작업 디렉토리는 노트북 파일이 있는 폴더다. 프로젝트 루트에서 작업하고 싶다면 %cd ..로 이동하거나, VS Code의 "Terminal: Select Default Shell" 설정을 확인해보자.
5. 노트북 시작 템플릿 (권장)
새 노트북 시작 시 첫 번째 셀에 다음 설정을 넣어두면 편리하다.
# 노트북 초기 설정 (첫 번째 셀)
# Python 파일 자동 리로드
%load_ext autoreload
%autoreload 2
# 그래프 인라인 표시
%matplotlib inline
# 환경 변수 로드
from dotenv import load_dotenv
load_dotenv()
# 경고 메시지 숨기기 (선택)
import warnings
warnings.filterwarnings('ignore')
print("✅ 노트북 설정 완료!")
실행 번호 이해하기
셀 옆의 In [1], In [2] 번호는 실행 순서를 나타낸다.
In [1]: 첫 번째로 실행된 셀
In [*]: 현재 실행 중인 셀
In [ ]: 아직 실행되지 않은 셀
⚠️ 순서 주의 셀을 위에서 아래가 아닌 순서로 실행하면 번호가 뒤섞인다. 예: In [5] → In [2] → In [7]. 노트북 검증 시 "Restart Kernel and Run All"로 처음부터 순서대로 실행하여 확인하자.
하이브리드 워크플로우
Jupyter Notebook으로 탐색 → 구현 → 테스트 → 활용의 4단계 워크플로우를 통해 효율적인 개발이 가능하다.
하이브리드 워크플로우 4단계
탐색 (Jupyter): 데이터 구조 확인, 여러 방법 시도, 에러 케이스 발견
구현 (Python 파일): 검증된 로직을 함수로 추출, 타입 힌트와 에러 처리 추가
테스트 (pytest): 정상 케이스와 엣지 케이스 테스트 작성
활용 (Jupyter): 구현한 함수를 노트북에서 import하여 실제 분석에 사용
Step 1: Jupyter에서 탐색
데이터 통계 분석 유틸리티를 만드는 상황을 예로 들어보자. 먼저 노트북에서 여러 방법을 시도하며 로직을 탐색한다.
explore_stats.ipynb
# 데이터 통계 계산 실험
sales_data = [150, 230, 180, 320, 275, 190]
# 기본 통계 계산
print(f"합계: {sum(sales_data)}")
print(f"평균: {sum(sales_data) / len(sales_data):.1f}")
print(f"최대: {max(sales_data)}")
print(f"최소: {min(sales_data)}")
# 빈 리스트 테스트 → 문제 발견!
empty_data = []
try:
avg = sum(empty_data) / len(empty_data)
except ZeroDivisionError:
print("⚠️ 빈 리스트는 처리할 수 없음!")
Step 2: Python 파일로 구현
노트북에서 검증한 로직을 함수로 추출하고, 타입 힌트와 에러 처리를 추가한다.
data_utils.py
from typing import List, Dict
def calculate_stats(numbers: List[float]) -> Dict[str, float]:
"""숫자 리스트의 기본 통계를 계산합니다."""
if not numbers:
raise ValueError("빈 리스트의 통계를 계산할 수 없습니다")
return {
"sum": sum(numbers),
"average": sum(numbers) / len(numbers),
"max": max(numbers),
"min": min(numbers),
"count": len(numbers)
}
Step 3: pytest로 검증
정상 케이스와 엣지 케이스(빈 리스트)에 대한 테스트를 작성한다.
test_data_utils.py
import pytest
from data_utils import calculate_stats
def test_calculate_stats_normal():
result = calculate_stats([10, 20, 30])
assert result["sum"] == 60
assert result["average"] == 20.0
assert result["count"] == 3
def test_calculate_stats_empty_raises_error():
with pytest.raises(ValueError):
calculate_stats([])
Step 4: 노트북에서 Python 파일 활용
구현한 함수를 노트북에서 import하여 실제 데이터 분석에 활용한다.
analysis.ipynb
# 구현한 함수를 노트북에서 import하여 사용
from data_utils import calculate_stats
# 월별 매출 데이터 분석
monthly_sales = [150, 230, 180, 320, 275, 190]
stats = calculate_stats(monthly_sales)
print(f"총 매출: {stats['sum']:,}원")
print(f"평균 매출: {stats['average']:,.1f}원")
print(f"최대 매출: {stats['max']:,}원")
💡 팁 이 워크플로우의 핵심은 탐색과 구현의 분리다. 노트북에서 실험한 코드를 그대로 프로덕션에 사용하지 않고, Python 파일로 정리하여 테스트 가능한 형태로 만드는 것이 권장된다.
Python 파일 ↔ Jupyter 변환
Python 파일 → Jupyter
VS Code에서 Python 파일을 열고 우클릭 → "Export as Jupyter Notebook"을 선택하면 노트북으로 변환할 수 있다. 또는 # %% 마커를 사용하여 셀 경계를 지정할 수 있다.
# calculator.py - 셀 마커 사용 예시
# %% [markdown]
# # 계산기 함수
# %%
def add(a: int, b: int) -> int:
return a + b
# %%
# 테스트
result = add(2, 3)
print(f"2 + 3 = {result}")
Jupyter → Python 파일
VS Code에서 노트북을 열고 우클릭 → "Export Current Python File to Python Script"를 선택하거나, 터미널에서 nbconvert를 사용할 수 있다.
# nbconvert를 사용한 변환
uv run jupyter nbconvert --to python notebook.ipynb
Git 관리 모범 사례
Jupyter 노트북은 실행 결과(출력, 이미지 등)가 파일에 포함되어 Git diff가 복잡해질 수 있다. 다음과 같은 관리 방법이 권장된다.
# 단일 노트북
uv run jupyter nbconvert --clear-output --inplace notebook.ipynb
# 모든 노트북 (bash 4.0+ 또는 zsh)
uv run jupyter nbconvert --clear-output --inplace **/*.ipynb
# bash에서 globstar 활성화 필요 시
shopt -s globstar # bash 4.0+에서 ** 패턴 활성화
# 또는 find 명령어 사용 (모든 쉘 호환)
find . -name "*.ipynb" -exec uv run jupyter nbconvert --clear-output --inplace {} \;
💡 쉘 호환성 참고 **/*.ipynb 패턴은 bash에서 shopt -s globstar 설정이 필요하다. zsh는 기본 지원된다. 확실하지 않다면 find 명령어를 사용하자.
💡 추천 워크플로우 • 탐색 노트북: Git에 추가하되, 실험용이므로 자주 커밋하지 않음 • 중요 로직: Python 파일로 추출 → Git 커밋 • 최종 노트북: 출력 제거 후 커밋
VS Code Jupyter 고급 기능
VS Code Jupyter 확장은 단순한 노트북 뷰어가 아니다. 개발 생산성을 높이는 다양한 고급 기능을 제공한다.
⚠️ VS Code 전용 기능 아래 기능들은 VS Code에서 .ipynb 파일을 열었을 때만 사용할 수 있다. JupyterLab 웹 인터페이스(jupyter lab 명령으로 실행)에서는 다른 방식으로 변수를 확인해야 한다.
1. 변수 탐색기 (Variables)
현재 정의된 모든 변수의 값을 실시간으로 확인할 수 있다.
VS Code에서 사용하기
활성화: 노트북 상단의 "Variables" 버튼 클릭 (또는 Ctrl+Shift+P → "Jupyter: Focus on Variables View")
기능: 변수 이름, 타입, 크기, 값 미리보기
DataFrame: 더블클릭하면 테이블 형태로 데이터 탐색 가능
JupyterLab에서 변수 확인하기
JupyterLab 웹 인터페이스에서는 코드로 변수를 확인한다.
# JupyterLab에서 변수 확인하는 방법
# 방법 1: %whos 매직 명령어 - 모든 변수 목록
%whos
# 방법 2: %who 매직 명령어 - 변수 이름만
%who
# 방법 3: dir() 함수 - 현재 네임스페이스의 모든 이름
[name for name in dir() if not name.startswith('_')]
# 방법 4: 특정 변수 타입만 확인
%who str # 문자열 변수만
%who int # 정수 변수만
%who list # 리스트만
💡 팁 VS Code: 큰 DataFrame이나 리스트는 변수 탐색기에서 더블클릭하면 별도 탭에서 정렬, 필터링, 검색이 가능하다. JupyterLab: DataFrame은 셀에서 변수명만 입력하면 테이블 형태로 예쁘게 출력된다.
2. 셀 디버깅
노트북 셀에서도 브레이크포인트를 설정하고 디버깅할 수 있다.
브레이크포인트: 코드 라인 번호 왼쪽 클릭
디버그 실행: 셀 옆 드롭다운 → "Debug Cell" 선택
기능: 스텝 실행, 변수 검사, 콜 스택 확인
# 디버깅 예시 - 라인 3에 브레이크포인트 설정
def calculate_total(items):
total = 0
for item in items: # ← 여기에 브레이크포인트
total += item['price'] * item['quantity']
return total
items = [{'price': 100, 'quantity': 2}, {'price': 50, 'quantity': 3}]
result = calculate_total(items)
3. 인터랙티브 윈도우
Python 파일(.py)에서도 노트북처럼 셀 단위 실행이 가능하다.
# my_script.py - # %% 마커로 셀 구분
# %%
# 첫 번째 셀 - 데이터 로드
import pandas as pd
data = pd.read_csv('sales.csv')
# %%
# 두 번째 셀 - 데이터 분석
data.describe()
# %%
# 세 번째 셀 - 시각화
data.plot(kind='bar')
실행: 각 셀 위의 "Run Cell" 버튼 또는 Shift+Enter
장점: Python 파일의 Git 관리 편의성 + 노트북의 인터랙티브 실행
변환: 우클릭 → "Export as Jupyter Notebook"으로 .ipynb 변환 가능
4. 유용한 VS Code 단축키
단축키
기능
Ctrl+Shift+P → "Jupyter"
모든 Jupyter 명령어 검색
Escape → O
셀 출력 토글 (숨기기/보이기)
Escape → L
라인 번호 토글
주의사항 및 팁
주의사항 • 셀 실행 순서: 셀을 위에서 아래로 순서대로 실행해야 한다. 순서가 뒤섞이면 예상치 못한 결과가 발생할 수 있다. • 변수 상태: 이전 셀의 변수가 메모리에 남아있으므로 혼란이 발생할 수 있다. "Restart Kernel" 기능으로 초기화할 수 있다. • 프로덕션 코드 아님: 노트북 코드는 반드시 Python 파일로 리팩토링하여 사용해야 한다.
권장 사항 • Kernel 재시작: 변수 상태가 꼬였을 때 상단 메뉴에서 "Restart Kernel" 사용 • 모든 셀 실행: 전체 노트북 검증 시 "Run All" 기능 활용 • Markdown 활용: 각 셀의 목적을 Markdown으로 설명하면 가독성이 향상됨 • 함수 분리: 재사용 가능한 코드는 Python 파일로 분리
[실제 테스트 필요한 부분] • VS Code Jupyter 확장의 단축키는 버전에 따라 다를 수 있다 • nbconvert의 --inplace 옵션 동작은 Jupyter 버전에 따라 상이할 수 있다 • Windows 환경에서의 경로 처리 방식 확인 필요
자주 묻는 질문 ❓
Q: Jupyter Notebook과 JupyterLab의 차이점은?
A: Jupyter Notebook은 단일 문서 인터페이스이고, JupyterLab은 파일 탐색기, 터미널, 여러 노트북을 탭으로 열 수 있는 통합 개발 환경이다. VS Code에서 사용하는 경우 VS Code 자체가 IDE 역할을 하므로 Jupyter Notebook으로 충분하다.
Q: 노트북 파일은 Git에 커밋해야 하나?
A: 탐색용 노트북은 선택적으로 커밋하고, 중요한 분석 결과나 문서화된 노트북은 출력을 제거한 후 커밋하는 것이 권장된다. 핵심 로직은 반드시 Python 파일로 추출하여 관리한다.
Q: 노트북에서 만든 함수를 Python 파일로 옮기는 기준은?
A: 재사용 가능성이 있거나, 테스트가 필요하거나, 프로덕션에서 사용될 코드는 Python 파일로 옮기는 것이 권장된다. 일회성 탐색 코드는 노트북에 그대로 둬도 된다.
