Jupyter Notebook 如果只被當成一個能寫代碼的記事本就浪費了它一半的價值。它真正的用法是把代碼、數據、圖表、說明文字和運行結果放在同一份文檔里讓分析過程可以逐段回放、逐段檢查、逐段復用。NTMSS2023 第 4 天第 1 節的內容是 “Intro to Jupyter notebooks”正好是這套工具的入門入口。這篇教程會按照實際使用的順序來寫先看 Jupyter 能做什么、大概需要什么環境然后走一遍安裝、啟動、新建、運行、導出、批量執行的完整流程。最后把最容易踩的坑集中列出來方便你遇到問題時直接對照排查。無論你是剛接觸 Python 數據分析還是想在團隊里統一分析流程這篇文章都可以直接作為第一份操作手冊。1. Jupyter Notebook 核心能力速覽Jupyter Notebook 嚴格來說不是單一的軟件而是一套組件組合瀏覽器里的交互式界面、獨立運行的計算內核、文件格式 .ipynb、以及周邊導出和調度工具。這套結構決定了它的能力邊界。能力項說明項目類型交互式計算環境常用于數據分析、教學、算法原型驗證主要組成Notebook 界面、Kernel 內核、.ipynb 文件格式、nbconvert、JupyterLab支持語言通過安裝不同內核支持 Python、R、Julia 等最常見的是 Python啟動方式命令行啟動 JupyterLab 或 Notebook瀏覽器訪問遠程訪問默認只監聽本機可配置遠程訪問但需要額外處理安全認證批量任務可用 nbconvert --execute 或 papermill 批量執行筆記本接口能力提供 REST API也支持 Notebook 文件格式級調用交互能力支持 Markdown 單元格、代碼單元格、表格、圖片、交互式控件適合場景數據探索、課程教學、實驗記錄、論文復現、算法調試不適合場景大型工程開發、高并發服務、需要長期運行的獨立任務從這張表可以看出來Jupyter 的強項不是“部署一個服務”而是“讓一個分析過程可讀、可改、可重跑”。后面所有操作都圍繞這個核心展開。2. 適用場景與使用邊界先回答最實際的問題我要不要用 Jupyter用它解決什么問題最典型的適用場景是數據探索。拿到一批數據不想一開始就寫完整腳本而是想快速看看字段、分布、缺失值這時候 Jupyter 的逐格運行優勢非常明顯寫一小段、跑一小段、立刻看結果發現不對就改。對課程教學來說它可以把理論、公式、示意代碼和效果圖并排放在一起學生可以自己動手改參數重跑。對論文復現來說notebook 文件天然記錄了運行順序和中間輸出比零散的 .py 文件更容易還原當時的分析過程。它不適合什么場景如果任務是一個完整的后端服務比如 Web API、爬蟲調度器、消息隊列消費者那不應該用 notebook 長期運行因為 kernel 斷開會話就丟也不方便做進程守護。如果代碼庫很大、模塊很多、需要嚴格測試和類型檢查Jupyter 也不是最合適的主戰場它更適合做研究階段的原型工程化階段仍然建議把穩定代碼抽成 .py 模塊和測試用例。還有一個必須強調的使用邊界Jupyter 里運行代碼時單元格之間是共享全部變量的這帶來便利也帶來隱患。前一個單元格定義了變量后一個單元格可能隱式依賴它重跑整個 notebook 時順序一亂結果就變樣。所以要養成“從頭到尾重跑一遍”的驗證習慣。涉及敏感數據時不要把明文密鑰、手機號、身份證號、業務隱私數據直接放在 notebook 里也不要隨手把帶敏感輸出的 notebook 分享出去。本地演示用測試數據線上數據要脫敏后再進 notebook。3. 環境準備與前置條件Jupyter 的本質是一個 Python 包加瀏覽器界面環境準備并不復雜但要避免后面反復折騰依賴沖突所以環境隔離這一步不能省。3.1 操作系統的選擇Jupyter Notebook 官方支持 Windows、macOS 和主流 Linux 發行版。Windows 上安裝時要注意如果路徑中含中文或空格可能帶來一些兼容問題建議所有安裝目錄盡量用英文路徑。Linux 服務器上安裝時注意區分系統自帶的 Python 和通過包管理器安裝的 Python避免混用不同版本。3.2 Python 版本與虛擬環境檢查運行以下命令確認當前 Python 版本python --version pip --version如果還沒有 Python推薦先安裝 Miniconda體積比 Anaconda 小很多但足夠管理虛擬環境。使用 conda 或 venv 創建獨立環境不要讓 Jupyter 直接裝在系統 Python 里。使用 conda 創建環境conda create -n jupyter-env python3.11 -y conda activate jupyter-env如果系統里只有普通 Python可以用 venv 創建虛擬環境python -m venv jupyter-env # Windows: jupyter-env\Scripts\activate # Linux/macOS: source jupyter-env/bin/activate3.3 磁盤空間與依賴規劃Jupyter 本體占用空間很小但安裝數據分析常用庫比如 pandas、numpy、matplotlib會占用幾百 MB 到 1GB 以上。在服務器上使用時要提前給用戶目錄和臨時目錄留出空間。.ipynb 文件本身是 JSON 格式如果單元格里嵌入了大量圖片、大表格輸出文件會迅速膨脹所以要注意保存前清理不必要的輸出。4. 安裝部署與啟動方式環境準備好之后安裝和啟動 Jupyter 只需要幾條命令。這里推薦安裝 JupyterLab它是新版 Notebook 的功能超集既有傳統 Notebook 的文件列表又支持多標簽頁、插件、終端、代碼格式化等擴展功能。4.1 安裝 JupyterLabpip install jupyterlab安裝完成后確認版本jupyter lab --version如果是在服務器或容器中運行也可以考慮安裝完整的數據科學基礎包pip install pandas numpy matplotlib4.2 本地啟動服務默認情況下JupyterLab 只綁定在 127.0.0.1也就是只有本機能訪問這個默認策略比較安全建議保持。啟動命令如下jupyter lab啟動后終端會輸出一個帶 token 的訪問地址形如http://127.0.0.1:8888/lab?token一串隨機字符瀏覽器打開這個地址就可以進入工作臺。如果你想手動指定端口比如端口 8889 被占用時jupyter lab --port 8889如果想指定監聽地址和端口比如在遠程服務器上使用需要顯式設置jupyter lab --ip 0.0.0.0 --port 8888 --no-browser這里必須提醒將 IP 設置為 0.0.0.0 意味著同一網絡內其他機器都可以訪問你的服務沒有設置密碼時非常危險。遠程使用時要先配置密碼或使用 token并且建議配合防火墻只放行可信 IP。不要把未保護的 Jupyter 暴露到公網。4.3 設置登錄密碼設置密碼可以避免每次復制 tokenjupyter server password輸入兩次密碼后后續訪問到登錄頁輸入該密碼即可。這個密碼會寫入配置文件中權限需要由當前用戶控制。4.4 利用 JupyterLab 的桌面入口如果是個人電腦日常使用JupyterLab 安裝后通常會在開始菜單或應用程序目錄中生成快捷方式直接雙擊啟動即可。啟動后瀏覽器會打開工作臺界面左側是文件樹中間是文件編輯區。界面語言為英文但源碼和 Markdown 支持中文編輯。5. 功能測試與效果驗證安裝完成只是一個開始接下來要驗證 notebook 是否真的能run起來。下面按“新建—運行—導出”的主線走一遍。5.1 新建第一個 Notebook進入 JupyterLab 工作臺后點擊左側號在 Launcher 中找到 Python 3 圖標點擊即可新建一個 notebook。注意這里的 Python 3 代表當前環境里的默認 kernel。如果你是在 conda 環境里安裝的 jupyter但 Launcher 里沒有顯示這個環境的 Python說明 kernel 沒有注冊需要安裝 ipykernelpip install ipykernel python -m ipykernel install --user --name jupyter-env --display-name Python (jupyter-env)注冊完成后刷新瀏覽器頁面Launcher 里就會多一個對應的選項。5.2 單元格基本運行Notebook 由兩種單元格組成Code 單元格和 Markdown 單元格。Code 單元格用于運行程序按Shift Enter執行并跳到下一個單元格Markdown 單元格用于寫說明文字同樣按Shift Enter渲染。先在第一個 Code 單元格里寫一個最簡單的測試print(Hello Jupyter)按Shift Enter執行輸出區域應顯示Hello Jupyter。接著測試一下基本的 Python 操作data [1, 2, 3, 4, 5] mean sum(data) / len(data) print(fmean: {mean})此時說明 kernel 正常工作。注意變量data和mean已經存進了當前 kernel 的全局命名空間在后續任意單元格中都可以直接引用。5.3 Markdown 單元格與圖文混排在當前單元格上方點擊 “” 插入一個新單元格切換單元格類型為 Markdown輸入# 數據分析實驗記錄 - 數據來源示例數據 - 分析目標驗證均值計算 - 環境JupyterLab Python 3按Shift Enter渲染文檔會顯示標題和列表。這就是 notebook 比普通腳本直觀的原因代碼、輸出、筆記在同一個文件里按順序排列。5.4 可視化驗證數據分析和展示是 Jupyter 的標準功能。先安裝 matplotlib然后運行import matplotlib.pyplot as plt plt.plot([1, 2, 3, 4], [2, 4, 1, 3]) plt.title(Test Plot) plt.show()輸出區域應顯示折線圖。如果圖片能正常顯示說明 matplotlib 集成沒問題。需要說明的是在 notebook 中通常不需要顯式調用%matplotlib inline新版 JupyterLab 默認就能嵌入圖片但如果是舊版本 Notebook可能需要手動設置。5.5 時間開銷測試分析場景里經常需要關心一段代碼跑多久。用魔術命令%time或者%%time可以不額外寫代碼完成計時%%time total 0 for i in range(1000000): total i print(total)計時結果會顯示在單元格輸出中比如CPU times: user 62.3 ms, sys: 3.1 ms, total: 65.4 ms Wall time: 65.9 ms這個能力在排查性能問題時很實用。%time只對單條語句計時%%time對當前單元格整體計時。5.6 重新執行整個 NotebookNotebook 的一個常見坑是你只從上到下執行一次沒問題但修改中間某個單元格后后面單元格里的變量可能就變了。所以每次改動后最好通過菜單Run Run All Cells重跑整個 notebook驗證邏輯是否仍然正確。這個操作在正式分享或提交輸出前很有必要。5.7 保存與導出notebook 的自動保存默認開啟但建議長會話中手動按CtrlS保存。導出為其他格式使用菜單File Save and Export Notebook As可以導出為 Markdown、HTML、Python 腳本等。命令行導出在后面接口部分講批量場景更常用。6. 接口 API 與批量任務很多人只把 Jupyter 當個人工具用忽略了一個亮點它的文件格式和執行邏輯是可以被程序調用的。這意味著你可以批量執行若干 notebook、批量導出報告甚至把 notebook 當成一種可復現的“分析腳本”。6.1 命令行批量轉換nbconvertnbconvert 是 Jupyter 自帶的轉換工具。把一個 notebook 轉為 HTML 報告jupyter nbconvert --to html analysis.ipynb轉為 Markdownjupyter nbconvert --to markdown analysis.ipynb這個命令可以加--execute參數先執行所有單元格再導出jupyter nbconvert --to html --execute analysis.ipynb加上--ExecutePreprocessor.timeout600可以加大超時時間適合長時間運行的單元格jupyter nbconvert --to html --execute analysis.ipynb --ExecutePreprocessor.timeout600批量轉換多個 notebook 時可以直接把多個文件名放一起或者寫一個簡單的 shell 循環。例如在 Linux/macOS 下for file in notebooks/*.ipynb; do jupyter nbconvert --to html --execute $file doneWindows PowerShell 下可以寫Get-ChildItem notebooks\*.ipynb | ForEach-Object { jupyter nbconvert --to html --execute $_.FullName }這種方式的優勢是簡單每個 notebook 獨立執行失敗時該文件會報錯但不會影響其他文件。6.2 參數化批量執行papermill如果 notebook 里跑的是同一套分析邏輯只是輸入參數不同nbconvert 的缺點就暴露了每次都要手動改單元格里的變量。paper mill 是專門解決這個問題的工具通過在 notebook 中標記參數單元格讓外部命令注入參數然后批量執行并單獨保存輸出。安裝 papermillpip install papermill假設 notebook 中某個 Code 單元格是# 參數 input_file data/input.csv threshold 0.5用 papermill 執行并注入新參數papermill analysis.ipynb output/analysis_0.8.ipynb -p threshold 0.8 -p input_file data/input_2.csv它會把參數單元格替換為指定值然后從頭執行整個 notebook并把結果輸出到新文件。這樣可以一次跑多個參數組合papermill analysis.ipynb output/analysis_0.1.ipynb -p threshold 0.1 papermill analysis.ipynb output/analysis_0.5.ipynb -p threshold 0.5 papermill analysis.ipynb output/analysis_0.9.ipynb -p threshold 0.9執行完成后output 目錄下會保留每個參數組合對應的完整 notebook附帶全部運行輸出。這對參數掃描、敏感性分析、周期報表自動化非常有幫助。6.3 使用 Jupyter REST APIJupyter 服務本身也提供 HTTP 接口比如查看當前運行的內核、創建內核、執行代碼等。默認訪問需要 token可以在啟動日志里找到。向內核執行代碼需要先獲取 kernel id然后通過 WebSocket 發送消息這個過程比較復雜。相對實用的場景是列出服務狀態和 kernel 列表。列出 kernel 列表curl -H Authorization: token 你的token http://127.0.0.1:8888/api/kernels返回結果是一個 JSON 數組包含 name、kernel id、connections 等信息。用 Requests 也可以import requests url http://127.0.0.1:8888/api/kernels r requests.get(url, headers{Authorization: token 你的token}) print(r.json())如果你的主要訴求是“讓程序運行某個 notebook 并拿到結果”更推薦 nbconvert 或 papermill而不是直接調 API。直接調 REST API 適合做集成監控、自動化運維比如確認某個服務節點上的 kernel 還活著。6.4 任務隊列與失敗重試建議批量執行 notebook 時要考慮穩定性。建議每次執行都在獨立輸出目錄中保存結果文件避免覆蓋原文件。執行日志要保留哪個文件失敗、哪一步超時要有記錄。對于臨時失敗比如網絡下載依賴導致的失敗可以加一層重試先執行一次失敗后等幾秒再執行一次。對于參數類任務強烈建議把參數文件集中管理用 JSON 或 YAML 記錄參數組合方便復現{ task1: { input_file: data/input_1.csv, threshold: 0.5 }, task2: { input_file: data/input_2.csv, threshold: 0.8 } }然后寫一個 Python 腳本讀取 JSON 后調用 papermill 接口逐個執行。7. 資源占用與性能觀察Jupyter 不是重型應用但它的資源占用情況會直接決定你的工作流是否順暢。核心要觀察兩個維度內存占用和 kernel 占用。7.1 內存占用Jupyter 啟動后Node.js 前端進程和一個 Python kernel 進程會常駐。前端進程負責瀏覽器界面和文件服務kernel 進程負責執行代碼。內存占用不像固定指標取決于你加載了多少數據、多少庫。比如一個空 notebook 的 kernel 內存占用很低但一旦加載大 DataFrame內存會明顯上升。所以不要用“一個 kernel 占多少內存”來量化而要把top或任務管理器里的 python 進程當作觀察點。在 Linux 服務器上可以用top -u $USER或者用 htop 實時看htop如果頁面卡頓通常不是 Jupyter 本身的問題而是 kernel 正在執行大計算。此時瀏覽器請求等結果并不代表 Jupyter 卡死。7.2 內核數量與端口每新建一個 notebookJupyter 會對應一個 kernel 進程。打開的 notebook 越多后臺進程就越多。長時間不用的 notebook 應該關閉并關閉其 kernel否則會白占內存。可以通過菜單File Shut Down Kernel關閉指定 notebook 的內核也可以通過左側Running Terminals and Kernels面板統一管理。7.3 降低資源占用的實用方法不要在同一個 notebook 里加載多份大型數據集用不到的就釋放或刪除。大矩陣和中間結果變量要及時釋放del 變量名之后如果內存沒有立即下降可以調用import gc; gc.collect()。涉及長時間循環時優先用向量化寫法比如把 Python 循環改寫為 pandas 或 numpy 操作。帶圖像的單元格會被緩存到內存中輸出過多時重啟 kernel 會更干凈。如果是為了保留運行結果而保存 large output可以在保存前清空輸出再重跑一遍生成最終報告。8. 常見問題與排查方法問題現象可能原因排查方式解決方案瀏覽器打開地址后提示 404服務未啟動或地址端口寫錯檢查終端日志中的訪問 URL確認端口重新用jupyter lab啟動復制終端里的完整 URL啟動后找不到 token服務啟動時沒有打印 URL或終端滾動丟失執行jupyter server list查看當前服務和 token也可用jupyter server password設置固定密碼端口被占用另一個 Jupyter 服務或程序占用了 8888netstat -anofindstr 8888Windows或lsof -i:8888macOS/Linux新建 notebook 時沒有 Python 3 kernel當前環境沒有注冊 ipykernel運行jupyter kernelspec list查看已注冊內核執行python -m ipykernel install --user --name 環境名單元格執行后提示 ModuleNotFoundError模塊沒有安裝或安裝到了另外的 Python 環境在 notebook 里執行import sys; print(sys.executable)確認 kernel 使用的 Python 路徑在對應環境中執行pip install 包名代碼能跑但頁面不顯示圖片matplotlib 輸出嵌入配置問題檢查圖表代碼是否在正確單元格是否有plt.show()新版本一般自動嵌入舊版本可添加%matplotlib inlinenotebook 文件保存失敗權限不足或磁盤空間不足查看終端日志檢查目錄寫權限更換輸出目錄或調整用戶權限遠程訪問被拒絕服務只監聽 127.0.0.1或防火墻攔截檢查啟動命令是否有--ip 0.0.0.0檢查防火墻規則明確設置監聽地址配置密碼并放行端口批量執行時某個文件卡住單元格中有長循環或等待超時增加 ExecutePreprocessor timeout--ExecutePreprocessor.timeout600長時間運行后頁面無響應kernel 內存過大或正在計算查看系統資源占用查看終端日志重啟 kernel減少單次計算量9. 最佳實踐與使用建議Jupyter 用久了很多人會發現最影響效率的不是功能不會用而是 notebook 結構混亂、難以復現。下面幾條實踐建議適合個人和團隊場景。第一一個 notebook 只解決一個分析問題。不要把數據清洗、特征工程、建模、繪圖、導出報告全塞進同一個文件。按階段拆成多個 notebook比如01_load_data.ipynb、02_clean_data.ipynb、03_model.ipynb每個文件專注一個環節后續調用和回溯都方便。第二單元格的順序就是執行邏輯的順序。從上到下寫完每次修改后都完整重跑一次。不要在 notebook 中間隨機跳著執行否則輸出的結果只能代表當前順序下的狀態不是可復現的結果。分享前用Run All Cells重跑一遍確認所有輸出都能復現。第三控制單元格粒度。一個單元格里寫幾千行代碼和寫一個 .py 腳本沒區別。合理粒度是每個單元格完成一個獨立子任務函數定義、參數設置、數據加載、可視化、結果統計分別放在不同單元格。這樣別人閱讀時可以按段理解邏輯。第四敏感信息不要留在 notebook 里。數據庫密碼、API Key、個人數據等不應該寫入代碼單元格或輸出區域。如果必須做配置用環境變量或單獨的配置文件并在提交前清理輸出。第五版本控制要同步。.ipynb 是 JSON 格式直接放進 Git 會導致 diff 難讀而且輸出變化會造成大量無關改動。團隊協作時可以把最終版本導出為 .py 或 Markdown 審查也可以在 Git 中配置清理工具過濾輸出。如果只是自己使用至少要做到模型文件、輸入數據、輸出結果分別放在獨立目錄中notebook 文件按日期或版本命名。第六依賴環境要記錄。在項目根目錄維護 requirements.txt 或 environment.yml。這樣換機器或換環境時一條命令就能恢復依賴pip freeze requirements.txt # 或 conda env export environment.yml恢復環境pip install -r requirements.txt # 或 conda env create -f environment.yml第七批量執行時先小范圍測試。第一次用 papermill 批量跑 20 個參數組合前先跑 1 個驗證 notebook 能正常執行、輸出路徑正確。確認沒問題后再擴大到全部參數。批量任務要保留日志以便定位哪個參數組合執行失敗。第八注意遠程服務的訪問邊界。如果是在服務器上用 Jupyter建議啟用密碼認證、只監聽可信 IP、通過 SSH 隧道訪問而不是直接暴露公網。從安全穩定角度考慮公共服務部署不應該依賴 notebook 長期進程。10. 總結與下一步Jupyter Notebook 最值得嘗試的點是把“寫代碼”和“寫分析文檔”合并成同一件事。你可以在一個 .ipynb 文件里同時保留思路、代碼、圖表和結論而且隨時可以重新執行。最開始拿到一個 notebook 時先跑一遍Run All Cells再逐段修改學習理解每個單元格做了什么是上手最快的方式。最容易踩的坑有兩個第一環境混亂模塊裝到了別的 Python 環境導致啟動后找不到包第二單元格執行順序混亂導致最終結果無法復現。只要把虛擬環境和“重跑全部”這兩個習慣養成大部分 Jupyter 使用問題都能規避。下一步可以按自己的方向繼續擴展學習 JupyterLab 的快捷鍵和分屏操作提升日常編輯效率。研究 papermill 與參數化執行把你的 notebook 變成可批量執行的自動分析流程。嘗試 Jupyter Book把多個 notebook 組織成在線閱讀文檔。在云端平臺里使用 Jupyter比如通過 Binder 快速分享教學示例或使用云端 GPU 跑模型實驗。將穩定代碼從 notebook 中抽成 .py 模塊再通過 notebook 做調用演示兼顧工程化和可讀性。Jupyter 的關鍵不是某個花哨功能而是讓你的分析過程可以被記錄、被解釋、被復用。從這節課的內容出發先跑通一個最小示例再逐步加入你要處理的數據和方法就是最穩的前進路徑。