Raspberry Pi OS預裝了Python，你需要使用其虛擬環境來安裝包。今天出版的最新一期《The MagPi》雜志刊登了我們文檔負責人Nate Contino撰寫的一篇實用教程，幫助你入門。

Raspberry Pi OS預裝了Python 3。干擾系統Python的安裝可能會給你的操作系統帶來問題。安裝第三方Python庫時，請務必使用正確的包管理工具。

在Linux上，你可以通過兩種方式安裝Python依賴：

使用apt安裝預配置的系統包

• 在虛擬環境中使用Python的依賴管理器pip安裝庫

可以在 Thonny 內部創建虛擬環境，也可以通過命令行創建虛擬環境。

使用apt安裝Python包

通過apt安裝的包是專門為Raspberry Pi OS打包的。這些包通常已經過預編譯，因此安裝速度更快。由于apt管理所有包的依賴項，因此使用此方法安裝包括運行該包所需的所有子依賴項。如果你卸載包，apt還可以確保你不會破壞其他包。

例如，要安裝支持Raspberry Pi Build HAT的Python 3庫，請運行以下命令：

$ sudo apt install python3-build-hat

要查找通過apt分發的Python包，請使用apt search。在大多數情況下，Python包使用前綴python-或python3-：例如，你可以在python3-numpy下找到numpy包。

使用pip安裝Python庫

在Raspberry Pi OS的舊版本中，你可以使用pip直接將庫安裝到系統版本的Python中。但從Raspberry Pi OS Bookworm版本開始，用戶無法直接將庫安裝到系統版本的Python中。

在Raspberry Pi OS Bookworm中嘗試使用pip安裝包會導致錯誤。

相反，應將庫安裝到虛擬環境（venv）中。若要在系統級別為所有用戶安裝庫，請使用apt進行安裝。

嘗試在系統范圍內安裝Python包會輸出類似于以下的錯誤：

$ pip install buildhaterror: externally-managed-environment
× This environment is externally managed╰─> To install Python packages system-wide, try apt install python3-xyz, where xyz is the package you are trying to install.
If you wish to install a non-Debian-packaged Python package, create a virtual environment using python3 -m venv path/to/venv. Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make sure you have python3-full installed.
For more information visit http://rptl.io/venv
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.hint: See PEP 668 for the detailed specification.

長期以來，Python用戶一直需要處理像apt這樣的操作系統包管理器和像pip這樣的Python專用包管理工具之間的沖突。這些沖突包括Python級別的API不兼容性和文件所有權沖突。

從Raspberry Pi OS Bookworm版本開始，通過pip安裝的包必須安裝到Python虛擬環境（venv）中。虛擬環境是一個容器，你可以在其中安全地安裝第三方模塊，這樣它們就不會干擾你的系統Python。

在虛擬環境中使用pip

要使用虛擬環境，請創建一個容器來存儲環境。根據你想要如何使用Python，有幾種方法可以做到這一點：

按項目環境

在項目文件夾中創建一個虛擬環境，以安裝該項目本地的包。

許多用戶為每個Python項目創建單獨的虛擬環境。將虛擬環境定位在每個項目的根文件夾中，通常使用一個共享的名稱，如env。從每個項目的根文件夾運行以下命令來創建虛擬環境配置文件夾：

$ python -m venv env

在開始處理項目之前，從項目的根目錄運行以下命令以開始使用虛擬環境：

$ source env/bin/activate

然后你應該會看到一個類似于以下的提示符：

$ (.env) $

當你完成一個項目的工作后，從任何目錄運行以下命令以退出虛擬環境：

$ deactivate

按用戶環境

而不是為你的每個Python項目創建一個虛擬環境，你可以為你的用戶帳戶創建一個單獨的虛擬環境。在運行任何Python代碼之前激活該虛擬環境。對于跨項目共享許多庫的工作流，這種方法可能更方便。

在為整個用戶帳戶的多個項目創建虛擬環境時，請考慮將虛擬環境配置文件定位在你的主目錄中。將你的配置文件存儲在一個名稱以句點開頭的文件夾中，以便默認隱藏該文件夾，防止其使你的主文件夾雜亂無章。

在主目錄中添加一個虛擬環境，以便在多個項目中使用并共享包。

使用以下命令在當前用戶的主目錄中的隱藏文件夾中創建一個虛擬環境：

$ python -m venv ~/.env

從任何目錄運行以下命令以開始使用虛擬環境：

$ source ~/.env/bin/activate

然后你應該會看到一個類似于以下的提示符：

$ (.env) $

要退出虛擬環境，從任何目錄運行以下命令：

$ deactivate

創建虛擬環境

運行以下命令以創建虛擬環境配置文件夾，將替換為你想要為虛擬環境使用的名稱（例如env）：

$ python -m venv

進入虛擬環境

然后，在虛擬環境配置文件夾中執行bin/activate腳本來進入虛擬環境：

$ source /bin/activate

然后你應該會看到一個類似于以下的提示符：

$ () $

()命令提示符前綴表示當前終端會話處于名為的虛擬環境中。

要檢查你是否處于虛擬環境中，請使用pip list查看已安裝包的列表：

$ () $ pip listPackage Version---------- -------pip 23.0.1setuptools 66.1.1

列表應該比你的系統Python中安裝的包列表短得多?，F在你可以安全地使用pip安裝包。在虛擬環境中，你使用pip安裝的任何包都只安裝到該虛擬環境中。在虛擬環境中，python或python3命令會自動使用虛擬環境的Python版本和已安裝包，而不是系統Python。

小貼士：在文件夾名稱前傳遞–system-site-packages標志，以將當前系統Python安裝中已安裝的所有包預加載到虛擬環境中。

退出虛擬環境

要退出虛擬環境，運行以下命令：

$ () $ deactivate

使用Thonny編輯器

我們建議在Raspberry Pi上使用Thonny編輯Python代碼。

默認情況下，Thonny使用系統Python。但是，你可以通過點擊Thonny窗口右下角的解釋器菜單來切換到使用Python虛擬環境。選擇一個已配置的環境或使用“配置解釋器”配置一個新的虛擬環境。