Python本地安装第三方包到lib目录后调用报ModuleNotFoundError如何解决

错误根源 #

你当前的操作错误在于：将第三方包安装到./lib目录后，通过from lib import 包名的方式导入，破坏了第三方包的原有顶层命名空间。
绝大多数第三方包（包括pendulum、click、python-docx）内部均使用绝对导入引用自身子模块，比如pendulum内部会直接写from pendulum import xxx，当你把它放在lib目录下后，它的顶层命名空间变成了lib.pendulum，Python无法找到顶层的pendulum模块，因此触发内部导入报错。
而colorama可以正常使用，是因为其代码结构简单，内部没有依赖自身顶层包名的绝对导入逻辑，刚好兼容了你的导入方式。

解决方案 #

以下3种方案均可解决问题，推荐优先使用方案3：

方案1：代码内添加模块搜索路径（无需修改运行方式） #

在你所有需要导入依赖的代码文件最开头，添加如下代码，将lib目录加入Python的模块搜索路径，之后直接按原生方式导入依赖即可，无需加lib前缀：

import sys
from pathlib import Path
# 将lib目录加入搜索路径优先级最高的位置
sys.path.insert(0, str(Path(__file__).parent.resolve() / "lib"))

# 后续直接正常导入即可
import colorama
import click
import pendulum
import docx

注意：无需保留lib/__init__.py文件，可直接删除。

方案2：临时设置PYTHONPATH环境变量（无需修改代码） #

运行代码前先设置PYTHONPATH环境变量指向当前项目的lib目录，之后直接运行代码即可：

• Windows CMD环境：

set PYTHONPATH=./lib
python test.py

• Windows PowerShell环境：

$env:PYTHONPATH="./lib"
python test.py

• Linux/macOS 终端环境：

export PYTHONPATH=./lib
python test.py

方案3：使用Python虚拟环境管理本地依赖（官方推荐最佳实践） #

你无需自行创建lib目录存储依赖，Python原生提供虚拟环境机制专门用于项目本地依赖隔离，操作步骤如下：

1. 删除当前项目下的lib目录，取消你之前写的from lib import xxx相关导入代码
2. 在项目根目录执行命令创建虚拟环境：

python -m venv venv

3. 激活虚拟环境：

• Windows CMD：venv\Scripts\activate.bat
• Windows PowerShell：venv\Scripts\Activate.ps1
• Linux/macOS：source venv/bin/activate

4. 激活后直接执行依赖安装命令，无需加-t参数：

pip install -r requirements.txt

5. 直接正常导入依赖运行代码即可，虚拟环境会自动处理所有模块搜索逻辑。

内容的提问来源于stack exchange，提问作者u84six