Python 與 R 執行環境

在 Settings → Runtimes 選擇 Notebook 和代理可使用的 Python、R 環境。Ready 表示直譯器已檢測或準備就緒，Enable 開關單獨決定代理能否選擇該環境。

可以選擇應用管理的環境或已有直譯器。使用前核對路徑、版本、Ready 狀態和 Enable 開關。系統 R 與應用管理的 R 可以並存。

閱讀平臺

macOSWindowsLinux

選擇會在章節間保留。

為專案選擇執行環境

記錄直譯器名稱、路徑和版本。首次 Python 分析可優先使用應用託管環境，避免修改其他研究依賴的環境。請求安裝軟體包前先在 Packages 中確認依賴是否已存在。檢視軟體包列表是隻讀操作，不會自動授予代理修改外部直譯器的權限。

執行失敗時，分別判斷直譯器不可用、缺少依賴、請求被拒絕或程式碼本身出錯。只有託管執行環境確實損壞時才考慮重灌，不能把所有分析錯誤都歸因於環境。復現結果時同時保留輸入版本、程式碼和執行環境資訊。

主頁面控制元件

控制元件	用途與邊界
Recheck	重新發現直譯器並檢測狀態，更新最後檢查時間；衝突的安裝任務進行時不可用
Network settings	開啟 Notebook 網路保護配置。提示條說明會話和包下載是否僅能訪問批准的域名
Let the Agent create environments	控制代理是否可建立環境及準備缺失執行時；關閉後仍可由使用者主動安裝或修復
Add interpreter…	開啟系統可執行檔案選擇器。選擇實際可執行檔案後，確認檢測到的路徑與 Ready 狀態
Download and set up	環境缺失時，準備應用管理的環境
安裝期間的 Cancel	請求取消安裝，等待狀態結束後再啟動其他操作
Retry setup	解決錯誤原因後重試
Enable [environment]	允許代理選擇該環境。禁用正在使用的環境時可能需要確認影響
Allow package install	已啟用的外部 Python 或 R 環境提供的單獨安裝授權；R 授權限定在選定的個人庫。檢視包列表不需要安裝授權
Packages [count]	開啟該直譯器的已安裝包清單
Reinstall	在重建應用管理環境前開啟確認

安裝應用管理的環境

安裝應用管理的 Python

1. 找到 Python → App-managed environment。
2. 選擇 Download and set up。
3. 檢視進度並等待，安裝期間出現 Cancel。
4. 成功後確認出現 conda: default-python、App-managed 與 Ready。
5. 檢查直譯器路徑及 Enable conda: default-python 開關。

確認 Ready、直譯器路徑和啟用狀態。包數量與版本隨安裝來源變化，不要把截圖中的臨時路徑用作長期環境位置。

安裝應用管理的 R

1. 開啟 Settings → Runtimes，滾動至 R。
2. 在 App-managed environment 下選擇 Download and set up。本機已有系統 R 時，仍可安裝這個獨立環境。
3. 等待下載和環境建立完成，期間保持應用開啟。如出現錯誤，先閱讀錯誤資訊再重試。
4. 確認顯示 conda: default-r、App-managed、Ready，並已啟用。
5. 開啟 Packages，在 Filter packages 輸入 r-base，核對 R 版本與渠道；清空篩選可檢視全部安裝包。

篩選 r-base 後，確認顯示已安裝 R 包及其版本、渠道。包總數取決於你的環境，可以與截圖不同。

接入已有直譯器

使用本機已經安裝的 R

選擇 Recheck，檢查發現的 R 路徑和版本。如果沒有出現目標直譯器，使用 Add interpreter… 選擇其可執行檔案。Ready 表示已檢測就緒，Enable 決定代理能否選擇該環境。

在 R Notebook 中檢查 R.home()，確認實際環境。需要安裝依賴時，按外部 R 包安裝步驟授權個人庫。

/opt/homebrew/bin/R 這類路徑表示系統安裝。

註冊並使用外部 Python

1. 準備需要使用的 Python 環境。
2. 選擇 Add interpreter…，選中 Python 可執行檔案，檢查 Ready、路徑和版本。
3. 使用 Recheck 複查，再啟用該環境。
4. 要求代理為 Notebook 明確選擇這個直譯器。
5. 先輸出 sys.executable 和 Python 版本，確認實際環境後再使用依賴。

若 macOS 檔案選擇器無法選中符號連結直譯器，選擇目標環境的實際可執行檔案。繫結後檢查 sys.executable。使用穩定安裝路徑，不要沿用截圖中的臨時示例路徑。

包安裝授權與實際結果

外部 Python 環境需要安裝新包時，先檢查 Allow package install 授權。允許安裝後，等待操作結束，並在同一環境中驗證匯入，再繼續分析。

安裝報告 403 Forbidden 或 destination resolves to a non-public network address 時，檢查受影響域名，按網路說明處理後再重試。這些錯誤屬於網路訪問問題，不能據此認定軟體包不存在。保持網路防護開啟。

禁用 Notebook 正在使用的環境

切換 Enable 後，先閱讀活動與空閒核心數量再確認。禁用可能關閉核心；重新啟用後，仍需為會話選擇可用執行時。該配置提供啟用、禁用控制元件，沒有單獨的 Remove interpreter 操作。

在外部 R 環境安裝包

已有 R 直譯器可以執行、但缺少依賴包時，使用這項功能。應用只授予一個已有個人庫的安裝權限，不授權系統庫或站點庫。

1. 在 Settings → Runtimes 啟用目標外部 R 環境，確認路徑和版本。
2. 在 Personal R package library 檢查檢測到的位置，或選擇合適的庫。沒有檢測結果時，使用 Advanced options → Choose library folder…，選擇該 R 直譯器可見且可寫的已有個人庫。此操作不會建立資料夾。
3. 啟用 Allow package install。授權前核對路徑：其他專案如果也使用這個庫，會受到包安裝變化的影響。
4. 透過應用的包管理操作請求安裝所需包，並明確指定該 R 環境。檢視安裝結果，按提示處理核心重啟。
5. 在該環境執行 R.home()、.libPaths()、library(PACKAGE_NAME) 和 packageVersion("PACKAGE_NAME")，將包名佔位符替換為實際包名。確認使用預期的庫後，再繼續分析。

關閉 Allow package install 可撤銷後續安裝授權，但不會解除安裝已經寫入的包。需要更換庫時先撤銷授權。沒有符合條件的資料夾時，在應用外準備個人 R 庫，或使用應用管理的環境；不要選擇系統庫來繞過檢查。

根據捕獲的鎖檔案恢復依賴

開啟已儲存結果的 Provenance → Environment，檢視捕獲的鎖檔案。有 Download bundle 時可下載恢復包，先閱讀包內說明和前置條件。

外部 R 需要可用的 renv 和受支援的 renv.lock；外部 Python 需要已有、受支援且固定雜湊的 requirements 鎖檔案。只有直譯器路徑或包名列表並不足夠。恢復環境必須滿足記錄的直譯器、平臺、架構和包管理器要求。

解壓恢復包，選擇自己擁有且可寫的新目標位置，按包內說明執行 restore-packages.py，傳入真實的直譯器與目標路徑。指令碼先核對前置條件和校驗值，再恢復包並檢查生效的版本與路徑。檢查失敗時應處理對應條件，不要修改鎖檔案來強行透過。Open-Science 不會接管或刪除這個外部目標位置。

這屬於有條件的依賴恢復，不是完整環境克隆。需要比較輸出時，重新開啟結果，在有受支援的捕獲執行過程時使用復現檢查。

檢查安裝包

選擇目標 Python 卡片的 Packages。對話方塊顯示該環境的路徑、包來源與狀態。

在 Filter packages 輸入 numpy 等包名，檢查版本與渠道，清空篩選可恢復列表，點選 Close 返回。

列名為 Name、Version、Build、Channel。Build 中的橫線表示未顯示構建值。這個對話方塊用於檢視清單；沒有安裝或解除安裝包的按鈕，不應在這裡尋找 “Install package” 輸入框。

用真實分析驗證環境

在所選環境執行小型計算，重新開啟輸出，與公共基準比較。執行與匯出步驟見 R Notebook。

資料質量工作流提供使用已有依賴的 Python 路線。計算成功不代表新增包安裝或核心重啟已經驗證。

匯入包失敗時，先檢查選中的執行環境及包清單。若下載因域名解析為保留地址而被拒絕，按網路處理。已有包能執行，不代表額外軟體包已經可以安裝。

其他分析前檢查所選環境是否包含所需包，必要時使用支援的包管理操作，閱讀真實結果，按要求重啟並驗證匯入。授權、進度卡片或 Ready 直譯器都不能代替匯入測試。

儲存結果的環境或執行證據不完整時，開啟 Provenance 檢視缺少的資訊。需要生成可用於復現檢查的新版本時，按環境準備步驟處理。數值匹配不會補齊缺失的來源證據。

確認實際使用的直譯器

準備好 Python 或 R 後，在對應語言的 Notebook 中執行下面的命令，檢查實際版本與路徑。設定頁列出的環境可能不止一個，以本次執行的輸出為準。

Python：

import sys
print(sys.version)
print(sys.executable)

R：

R.version.string
R.home()

然後讀取一份專案中的小表格，檢查行數並儲存結果。重新開啟應用後如需繼續分析，再執行一次檢查；歷史報告可讀取，不代表上次的記憶體變數仍在。Notebook 操作見Notebook 與執行證據。

維護和修復環境

取消安裝後重試

在 Download and set up 期間選擇 Cancel，等待出現 Runtime setup cancelled。選擇 Retry setup，等到 Ready 後開啟 Packages 檢查環境。前一個操作尚未結束時不要重複發起安裝。

重灌託管環境

1. 儲存需要保留的報告，記錄自行增加的依賴。
2. 在目標託管環境選擇 Reinstall。
3. 閱讀影響說明，再選擇 Reinstall runtime。
4. 等待 Ready，檢查 Packages。
5. 啟動新的 Notebook 單元，並重新開啟已有輸入和產出。

重灌會刪除並重建環境，正在執行的單元可能被取消並顯示 Run cancelled: the runtime was stopped while this cell was executing. Notebook 歷史可保留，但舊名稱空間不會恢復。重灌後先執行直譯器檢查，再重新執行產生所需變數的程式碼，並開啟已儲存檔案確認可用。

檔案保留不等於記憶體變數保留。繼續分析前重新執行必要程式碼。後來新增的軟體包可能需要重灌，基礎環境恢復不能證明每個額外依賴也已恢復。

開發構建提示 micromamba not found

原始碼開發版第一次安裝時，由於程序沒有找到 micromamba，在準備環境前失敗。

正式安裝包包含該程式。開發構建可在啟動程序環境中，將 OPEN_SCIENCE_MICROMAMBA_BIN 指向有效的 micromamba 可執行檔案，然後重啟開發例項。確認程式可執行後再重試；不要修改已安裝應用的內部檔案。

這個環境變數屬於開發啟動配置，不是 Runtimes 頁面的輸入欄位。不要透過刪除環境目錄處理此發現錯誤。