快捷導(dǎo)航

使用PyCharm和venv進(jìn)行Python項(xiàng)目環(huán)境配置避坑指南

更新時(shí)間：2025年04月21日 10:44:06 作者：Anarkh_Lee

在進(jìn)行 Python 項(xiàng)目開(kāi)發(fā)時(shí),一個(gè)干凈,隔離且配置正確的開(kāi)發(fā)環(huán)境至關(guān)重要,本文結(jié)合之前安裝 Vanna 庫(kù)時(shí)遇到的問(wèn)題,總結(jié)了使用 PyCharm 和 venv 進(jìn)行 Python 項(xiàng)目環(huán)境設(shè)置的最佳實(shí)踐和常見(jiàn)坑的解決方法,有需要的小伙伴可以參考下

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

核心概念：虛擬環(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)目可以擁有自己特定版本的庫(kù)，互不干擾。全局 Python 環(huán)境保持干凈。
版本控制: 可以輕松管理不同項(xiàng)目所需的特定庫(kù)版本。
部署一致性: 可以通過(guò) 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 為例)

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

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

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

python -m pip install --upgrade pip setuptools

安裝庫(kù):

pip install vanna

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

pip show vanna

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

常見(jiàn)問(wèn)題與解決方案 (Troubleshooting)

我們?cè)谥暗倪^(guò)程中遇到了幾個(gè)典型問(wèn)題：

問(wèn)題 1: ModuleNotFoundError: No module named ‘vanna’ 或 PyCharm 提示 Unresolved reference ‘vanna’

原因:

運(yùn)行腳本或 PyCharm 代碼檢查時(shí)使用的 Python 解釋器不是安裝了 Vanna 的那個(gè)虛擬環(huán)境。
安裝 Vanna 時(shí)，PyCharm 終端沒(méi)有激活虛擬環(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)境 (可通過(guò) pip show vanna 確認(rèn) Location)，請(qǐng)?jiān)谡_激活的虛擬環(huán)境終端中重新運(yùn)行 pip install vanna。

問(wèn)題 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

- **方法二 (更強(qiáng)制):** 如果方法一無(wú)效，使用 **ensurepip** 來(lái)重置：

python -m ensurepip --upgrade

- 通常在執(zhí)行這些更新命令**之后**，再嘗試 **pip install vanna**。

問(wèn)題 3: failed to create process

原因:

Windows 權(quán)限不足，無(wú)法在虛擬環(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)行開(kāi)發(fā)。

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

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

刪除項(xiàng)目下的 venv 文件夾。
打開(kāi)管理員命令提示符，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。

問(wèn)題 4: Error: Python packaging tool ‘setuptools’ not found

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

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

python -m pip install --upgrade setuptools

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

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

打開(kāi) 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

- 如果 **requirements.txt** 在其他位置 (例如 **config** 子目錄):

pip install -r config\requirements.txt

或者使用絕對(duì)路徑。

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

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

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

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

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

(請(qǐng)將 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ù)問(wèn)題的基礎(chǔ)。遇到問(wèn)題時(shí)，首先檢查：

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

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

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

您可能感興趣的文章: