在進(jìn)行 Python 項(xiàng)目開發(fā)時(shí)，一個(gè)干凈、隔離且配置正確的開發(fā)環(huán)境至關(guān)重要。尤其是在使用像 PyCharm 這樣的集成開發(fā)環(huán)境 (IDE) 時(shí)，正確理解和配置虛擬環(huán)境 (Virtual Environment) 是避免許多常見問題的關(guān)鍵。本文結(jié)合之前安裝 Vanna 庫時(shí)遇到的問題，總結(jié)了使用 PyCharm 和 venv 進(jìn)行 Python 項(xiàng)目環(huán)境設(shè)置的最佳實(shí)踐和常見“坑”的解決方法。

核心概念：虛擬環(huán)境 (venv)

Python 的虛擬環(huán)境 (通常使用內(nèi)置的 venv 模塊創(chuàng)建) 允許您為每個(gè)項(xiàng)目創(chuàng)建一個(gè)獨(dú)立的 Python 運(yùn)行環(huán)境。這意味著：

• 依賴隔離: 每個(gè)項(xiàng)目可以擁有自己特定版本的庫，互不干擾。全局 Python 環(huán)境保持干凈。
• 版本控制: 可以輕松管理不同項(xiàng)目所需的特定庫版本。
• 部署一致性: 可以通過 requirements.txt 文件精確復(fù)制項(xiàng)目的依賴環(huán)境。

強(qiáng)烈建議為每一個(gè)新的 Python 項(xiàng)目創(chuàng)建一個(gè)獨(dú)立的虛擬環(huán)境。

在 PyCharm 中創(chuàng)建項(xiàng)目與配置虛擬環(huán)境

1.新建項(xiàng)目: 在 PyCharm 中，選擇 File -> New Project…。

2.配置環(huán)境 (關(guān)鍵步驟):

• Location: 設(shè)置項(xiàng)目路徑 (例如 D:\MyVannaProject)。
• New environment using: 確保選擇 Virtualenv。
• Location: 接受默認(rèn)的 venv 子目錄 (例如 D:\MyVannaProject\venv)。
• Base interpreter: 選擇您系統(tǒng)安裝的基礎(chǔ) Python 3.x 解釋器。
• Inherit global site-packages: 不勾選。
• Make available to all projects: 不勾選。

3.創(chuàng)建: 點(diǎn)擊 Create。PyCharm 會(huì)自動(dòng)創(chuàng)建項(xiàng)目結(jié)構(gòu)和 venv 虛擬環(huán)境。

4.驗(yàn)證配置:

• 進(jìn)入 File -> Settings -> Project: [Your Project Name] -> Python Interpreter。
• 確認(rèn) “Python Interpreter” 指向的是項(xiàng)目 venv 目錄下的 python.exe (例如 D:\MyVannaProject\venv\Scripts\python.exe)。
• 包列表應(yīng)只包含 pip, setuptools 等基礎(chǔ)包。

使用 pip 安裝依賴 (以 Vanna 為例)

打開 PyCharm 終端: 點(diǎn)擊 IDE 底部的 Terminal 標(biāo)簽。

檢查激活狀態(tài) (!!!): 必須看到終端提示符行首有 (venv) 標(biāo)記。這表示虛擬環(huán)境已激活。如果未激活，請手動(dòng)運(yùn)行 .\venv\Scripts\activate 或重啟終端。

更新基礎(chǔ)工具 (推薦): 在激活的終端中運(yùn)行：

python -m pip install --upgrade pip setuptools

安裝庫:

pip install vanna

驗(yàn)證安裝位置:

pip show vanna

檢查輸出中的 Location: 是否指向 …\venv\Lib\site-packages。

常見問題與解決方案 (Troubleshooting)

我們在之前的過程中遇到了幾個(gè)典型問題：

問題 1: ModuleNotFoundError: No module named ‘vanna’ 或 PyCharm 提示 Unresolved reference ‘vanna’

原因:

• 運(yùn)行腳本或 PyCharm 代碼檢查時(shí)使用的 Python 解釋器不是安裝了 Vanna 的那個(gè)虛擬環(huán)境。
• 安裝 Vanna 時(shí)，PyCharm 終端沒有激活虛擬環(huán)境，導(dǎo)致 Vanna 被安裝到了全局環(huán)境或其他地方。

解決方案:

• 在 PyCharm 中，進(jìn)入 File -> Settings -> Project: … -> Python Interpreter，確保選擇的解釋器是項(xiàng)目 venv 下的 python.exe。
• 確保在 PyCharm 終端執(zhí)行 pip install 命令之前，提示符已有 (venv) 標(biāo)記。
• 如果 Vanna 錯(cuò)誤地安裝到了全局環(huán)境 (可通過 pip show vanna 確認(rèn) Location)，請?jiān)谡_激活的虛擬環(huán)境終端中重新運(yùn)行 pip install vanna。

問題 2: AttributeError: module ‘pkgutil’ has no attribute ‘ImpImporter’

原因: 這是較新的 Python 版本 (如 Python 3.12+) 與虛擬環(huán)境中可能存在的舊版本 setuptools (及其依賴 pkg_resources) 不兼容導(dǎo)致的。即使是新創(chuàng)建的 venv 也

可能包含不夠新的 setuptools。

解決方案:

方法一 (常用): 在激活的 venv 終端中，強(qiáng)制更新 pip 和 setuptools：

python -m pip install --upgrade pip setuptools

- **<font style="color:rgb(51, 57, 64);">方法二 (更強(qiáng)制):</font>**<font style="color:rgb(51, 57, 64);"> </font><font style="color:rgb(51, 57, 64);">如果方法一無效，使用</font><font style="color:rgb(51, 57, 64);"> </font>**<font style="color:rgb(51, 57, 64);">ensurepip</font>**<font style="color:rgb(51, 57, 64);"> </font><font style="color:rgb(51, 57, 64);">來重置：</font>

python -m ensurepip --upgrade

- <font style="color:rgb(51, 57, 64);">通常在執(zhí)行這些更新命令</font>**<font style="color:rgb(51, 57, 64);">之后</font>**<font style="color:rgb(51, 57, 64);">，再嘗試</font><font style="color:rgb(51, 57, 64);"> </font>**<font style="color:rgb(51, 57, 64);">pip install vanna</font>**<font style="color:rgb(51, 57, 64);">。</font>

問題 3: failed to create process

原因:

• Windows 權(quán)限不足，無法在虛擬環(huán)境目錄創(chuàng)建進(jìn)程。
• 防病毒軟件干擾。
• 虛擬環(huán)境本身已損壞。

解決方案:

嘗試管理員權(quán)限 (僅用于安裝): 關(guān)閉 PyCharm/cmd，右鍵以管理員身份運(yùn)行，激活 venv，然后執(zhí)行 pip install。安裝成功后，以普通用戶身份運(yùn)行 PyCharm 進(jìn)行開發(fā)。

檢查防病毒軟件: 暫時(shí)禁用，如果安裝成功，則添加 Python、項(xiàng)目和 venv 目錄到排除列表。

終極方案 (如果前兩者無效):

• 刪除項(xiàng)目下的 venv 文件夾。
• 打開管理員命令提示符，cd 到項(xiàng)目根目錄。
• 使用系統(tǒng) Python 重新創(chuàng)建 venv: C:\Path\To\System\Python\python.exe -m venv venv (替換為你的 Python 路徑)。
• 激活 venv: venv\Scripts\activate。
• 立即更新: python -m pip install --upgrade pip setuptools。
• 安裝依賴: pip install vanna。
• 回到 PyCharm (普通用戶)，重新配置項(xiàng)目解釋器指向這個(gè)新的 venv。

問題 4: Error: Python packaging tool ‘setuptools’ not found

原因: 虛擬環(huán)境中缺少基礎(chǔ)的 setuptools 包。

解決方案: 在激活的 venv 終端中安裝它：

python -m pip install --upgrade setuptools

使用 requirements.txt 安裝依賴 (CMD)

如果您需要從 requirements.txt 文件批量安裝依賴：

打開 CMD 并 cd 到項(xiàng)目根目錄 (例如 e:\project\xxx\xxxx)。

激活虛擬環(huán)境:

venv\Scripts\activate

確保看到 (venv) 提示符。

執(zhí)行安裝:

如果 requirements.txt 在當(dāng)前目錄 (項(xiàng)目根目錄):

pip install -r requirements.txt

- <font style="color:rgb(51, 57, 64);">如果</font><font style="color:rgb(51, 57, 64);"> </font>**<font style="color:rgb(51, 57, 64);">requirements.txt</font>**<font style="color:rgb(51, 57, 64);"> </font><font style="color:rgb(51, 57, 64);">在其他位置 (例如</font><font style="color:rgb(51, 57, 64);"> </font>**<font style="color:rgb(51, 57, 64);">config</font>**<font style="color:rgb(51, 57, 64);"> </font><font style="color:rgb(51, 57, 64);">子目錄):</font>

pip install -r config\requirements.txt

或者使用絕對路徑。

實(shí)戰(zhàn)的步驟

不知道為什么，我在PyCharm的終端中執(zhí)行pip install vanna永遠(yuǎn)都是安裝到全局中了。使用cmd操作就可以，所以本次安裝vanna都是通過cmd直接安裝的。

1.刪除舊環(huán)境： 使用文件資源管理器， 完全刪除 D:\myVannaProject\venv 文件夾。

2.在外部管理員終端創(chuàng)建新環(huán)境：

# 確保您在 D:\myVannaProject 目錄下，或者使用完整路徑
# 使用您系統(tǒng) Python 3 的 python.exe 來創(chuàng)建
C:\Users\anarkh\AppData\Local\Programs\Python\Python313\python.exe -m venv D:\myVannaProject\venv

(請將 C:\Users\anarkh\AppData\Local\Programs\Python\Python313\python.exe 替換為您 Python 3 的實(shí)際安裝路徑)

3.激活新環(huán)境（仍在管理員終端）：

D:\myVannaProject\venv\Scripts\activate

4.立即更新pip和setuptools：

python -m pip install --upgrade pip setuptools

5.安裝Vanna：

pip install vanna

安裝成功：

總結(jié)

Python 項(xiàng)目的環(huán)境配置，特別是虛擬環(huán)境的正確使用和 PyCharm 的相應(yīng)設(shè)置，是避免許多后續(xù)問題的基礎(chǔ)。遇到問題時(shí)，首先檢查：

• PyCharm 項(xiàng)目解釋器是否指向正確的 venv？
• PyCharm 終端是否已激活 (venv)？
• pip 和 setuptools 是否為最新兼容版本？
• 是否存在權(quán)限或防病毒軟件干擾？

遵循最佳實(shí)踐，耐心排查，就能搭建一個(gè)穩(wěn)定高效的開發(fā)環(huán)境。

到此這篇關(guān)于使用PyCharm和venv進(jìn)行Python項(xiàng)目環(huán)境配置避坑指南的文章就介紹到這了,更多相關(guān)PyCharm venv配置Python環(huán)境內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論