주피터 노트북(.ipynb) → 마크다운(.md) 변환 가이드
서론
주피터 노트북을 통해 EDA 를 진행했는데, 해당 내용을 Velog 에 공유하기 위해 방법을 찾아보았다.
주피터 노트북에서 실행하는 ipynb 파일 형식을 마크다운(md)으로 변환해주고, 이미지를 가져와 추가로 업로드 해주는 방식을 찾았다.
해당 포스트에서는 로컬에 설치된 주피터노트북의 ipynb 파일을 마크다운 파일로 변환(convert)할 수 있도록 가상 환경 설정 방법 및 변환 코드를 정리하였다.
1. 작업 디렉터리 이동
변환하고자 하는 노트북 파일이 있는 폴더로 이동한다.
*이때 터미널은 Anaconda Prompt 를 사용하였다.(Window 기준 시작 - 검색 창에서 검색하여 실행하였음.)
# 예: 내 문서/EDA 프로젝트 폴더로 이동
cd C:\Users\Minwoo\Documents\EDA_Project
# 파일 탐색기 내에서 경로를 선택하여 클립보드로 복사하고, cd + 붙여넣기(ctrl + V) 형식으로 작성하였다.
# 현재 위치 확인 (Windows)
cd
# 현재 위치 확인 (Mac/Linux)
pwd2. Conda 가상환경 생성 및 활성화
노트북 변환 시 기존 환경에 영향을 주지 않도록 가상환경을 사용한다.
(전역에 패키지를 설치하지 않고, 별도로 가상 환경을 구성하여 다른 프로젝트에 영향을 주지 않도록 함.)
# 가상환경 생성 (Python 3.10) 버전을 명시하지 않는 경우 최신 LTS 버전을 불러온다고 한다.
conda create -n eda_env python=3.10
# 가상환경 활성화
conda activate eda_env활성화 후에는 터미널 프롬프트 앞에
(eda_env)가 표시된다.
3. Jupyter와 nbconvert 설치
가상환경 안에서 필요한 패키지를 설치한다.
# Jupyter Notebook 설치
conda install jupyter
# nbconvert 설치 (Notebook → Markdown 변환용)
conda install nbconvertnbconvert는 노트북을 HTML, PDF, Markdown 등 다양한 형식으로 변환할 수 있다.
4. 가상환경 커널 등록
Jupyter에서 새로 만든 가상환경을 사용할 수 있도록 커널을 등록한다.
python -m ipykernel install --user --name eda_env --display-name "Python (EDA Env)"--name eda_env: 내부 식별용 이름--display-name "Python (EDA Env)": Jupyter에서 표시될 이름
이제 Jupyter Notebook에서 "Python (EDA Env)" 커널을 선택할 수 있다.
*등록 후에도 주피터 노트북을 실행하면, 커널 선택 창이 한번 더 나오기는 함.(윈도우 기준)
5. 노트북을 마크다운으로 변환
# 현재 디렉터리에 있는 노트북 파일 확인
dir # Windows
ls # Mac/Linux
# 예: 'eda_practice.ipynb' 파일을 Markdown으로 변환
jupyter nbconvert --to markdown eda_practice.ipynb# 코랩에서 변환할 때: 드라이브 접근 허용 먼저 한 뒤에 실행
from google.colab import drive
drive.mount('/content/drive')
# 코랩에서는 기본 경로개 /content 이므로, 정확한 경로를 지정해서 실행해줘야 정상 작동한다.
!jupyter nbconvert --to markdown "/content/drive/MyDrive/Colab Notebooks/eda_practice.ipynb"-
변환 결과:
eda_practice.md→ 마크다운 파일eda_practice_files/→ 그래프 이미지 등 별도 폴더
5.1. 변환 후 파일 구조 예시
# 기존 경로
eda_practice.md
EDA_Project/
├─ eda_practice.ipynb
└─ eda_practice_files/
├─ figure_1.png
├─ figure_2.png
└─ ...기존 경로에 md 파일이 생기고, 추가로 filename_files 폴더가 생김. 해당 폴더 안에 이미지가 들어있음.
- 변환 완료 후에는 md 파일을 메모장으로 열고, 내용을 모두 복사 한후 velog 에 붙여 넣기 하였다. 이미지 폴더는 따로 생성되므로(정렬도 차례대로 되어있음), 한개씩 선택하여 업로드 해주었다.
6. 변환 시 주의사항
- 패키지 호환성: 가상환경과 노트북 커널이 같은 Python 버전 및 패키지를 사용해야 함
- 이미지 출력:
matplotlib등 시각화 그래프의 크기를 조절하려면figsize설정 필요 - 경로 참조: 로컬 파일 경로를 마크다운에서도 그대로 사용할 수 있는지 확인
+ 변환할때 주피터 노트북이 실행 중이면 Ananocda Prompt 를 따로 조작할 수 없는 것 같음. 주피터 노트북을 실행 중이라면 종료 이후에 Prompt 에서 변환 명령어를 실행해주도록 하자.
7. 결론
주피터 노트북 파일을 마크다운으로 변환하면 블로그, Notion, GitHub 등 다양한 플랫폼에서 분석 결과를 공유할 수 있다.(마크다운 파일의 텍스트를 복사해서 쓰거나 업로드하고, 이미지는 추가로 첨부해줘야 함.)
이때 Conda Prompt 를 통해 가상환경을 사용하면 기존 환경에 영향을 주지 않고 안전하게 변환할 수 있으며, nbconvert 명령어 한 줄로 간단히 .md 파일을 생성할 수 있음.
visual studio code 에서는 다른 방법으로 가상환경을 설정하는데, 주피터 노트북은 명령어가 달라서 별도로 정리하였음.
공식문서 - Jupyter nbconvert User Guide
추가 내용
conda info --envs
# 모든 가상환경 목록 보기가상 환경을 활성화하기 이름이 잘 기억나지 않는다면 해당 명령어로 가상환경 목록을 확인할 수 있다.
*설정한 display name 은 실제 가상환경 이름과 다를 수 있다. 따라서 해당 명령어로 가상환경 이름을 확인하면 쉽게 활성화할 수 있다.
ps. 가상환경 내 새로운 라이브러리 설치시 자주 사용하였다.
