“ModuleNotFoundError“深度解析：Python模块导入问题的终极指南

ModuleNotFoundError: No module named 'mymodule'

import my_custom_module
# ModuleNotFoundError: No module named 'my_custom_module'

import sys
print(sys.path)  # 查看Python搜索路径

project/
├── main.py
└── mypackage/
    ├── __init__.py
    └── module.py

# main.py
from mypackage.module import func  # 正常工作

# module.py
from .submodule import helper  # 相对导入错误

# 诊断脚本：diagnose_imports.py
import sys
import os

print("=== Python 导入诊断 ===")
print(f"Python 版本: {sys.version}")
print(f"当前工作目录: {os.getcwd()}")
print("\n=== sys.path ===")
for path in sys.path:
    print(f" - {path}")
    
print("\n=== 环境变量 ===")
print(f"PYTHONPATH: {os.environ.get('PYTHONPATH', '未设置')}")
print(f"VIRTUAL_ENV: {os.environ.get('VIRTUAL_ENV', '未激活虚拟环境')}")

# 测试导入
module_name = input("\n请输入要测试的模块名: ")
try:
    module = __import__(module_name)
    print(f"\n✅ 成功导入 {module_name}!")
    print(f"模块位置: {module.__file__}")
except ModuleNotFoundError as e:
    print(f"\n❌ 导入失败: {e}")

import sys
from pathlib import Path

# 添加父目录到搜索路径
sys.path.append(str(Path(__file__).parent.parent))

# 添加特定目录
sys.path.insert(0, '/path/to/your/module')

# Linux/macOS
export PYTHONPATH="/path/to/your/module:$PYTHONPATH"

# Windows
set PYTHONPATH=C:\path\to\your\module;%PYTHONPATH%

pip install -e /path/to/your/package

# 错误：在脚本中使用相对导入
from .sibling import function

# 正确：
# 选项1：改为绝对导入
from package.sibling import function

# 选项2：将脚本作为模块运行
# python -m package.module

# 传统包（包含 __init__.py）
project/
└── package/
    ├── __init__.py
    └── module.py

# 命名空间包（Python 3.3+）
project/
├── part1/
│   └── package/
│       └── module1.py
└── part2/
    └── package/
        └── module2.py

# 使用
from package import module1, module2

# 创建虚拟环境
python -m venv myenv

# 激活
# Linux/macOS
source myenv/bin/activate

# Windows
myenv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 使用pyenv管理多版本
pyenv install 3.10.6
pyenv global 3.10.6

# 检查Python路径
which python
# /Users/username/.pyenv/shims/python

def load_plugin(plugin_name):
    try:
        # 动态导入
        plugin_module = __import__(f"plugins.{plugin_name}", fromlist=[""])
        return plugin_module.Plugin()
    except ModuleNotFoundError as e:
        print(f"无法加载插件 {plugin_name}: {e}")
        return None

# 安全加载
import importlib.util

def safe_import(module_name):
    spec = importlib.util.find_spec(module_name)
    if spec is None:
        print(f"模块 {module_name} 不存在")
        return None
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module

my_project/
├── src/
│   ├── core/
│   │   ├── __init__.py
│   │   └── models.py
│   ├── utils/
│   │   ├── __init__.py
│   │   └── helpers.py
│   └── main.py
├── tests/
│   ├── test_models.py
│   └── test_helpers.py
├── setup.py
└── pyproject.toml

from setuptools import setup, find_packages

setup(
    name="my_project",
    version="0.1",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
)

# conftest.py (确保测试可以导入src中的模块)
import sys
from pathlib import Path

root_dir = Path(__file__).parent.parent
sys.path.append(str(root_dir / "src"))

class ImageProcessor:
    def __init__(self):
        self._pil = None
    
    @property
    def pil(self):
        if self._pil is None:
            # 首次访问时导入
            import PIL.Image
            self._pil = PIL.Image
        return self._pil
    
    def process(self, image_path):
        img = self.pil.open(image_path)
        # 处理图像

project/
├── src/  # 所有源代码
│   └── package/
│       ├── __init__.py
│       ├── module1.py
│       └── subpackage/
│           ├── __init__.py
│           └── module2.py
├── tests/  # 测试代码
├── docs/   # 文档
├── setup.py
├── pyproject.toml
└── requirements.txt

# 推荐
from package.subpackage import module

# 避免（除非在包内部）
from . import sibling

# 1. 标准库
import os
import sys

# 2. 第三方库
import numpy as np
import pandas as pd

# 3. 本地应用/库
from . import helpers
from ..models import User

# 使用pylint检查导入问题
pylint --disable=all --enable=import-error your_module.py

# 使用bandit检查安全导入
bandit -r your_package/

# .github/workflows/ci.yml
name: Python CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.9'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
        pip install pylint bandit
    - name: Lint with pylint
      run: |
        pylint --disable=all --enable=import-error src/
    - name: Test with pytest
      run: |
        pytest tests/

# Dockerfile 示例
FROM python:3.9-slim

# 设置工作目录
WORKDIR /app

# 复制项目文件
COPY . .

# 安装依赖（包含可编辑模式）
RUN pip install --no-cache-dir -e .

# 正确设置PYTHONPATH
ENV PYTHONPATH="/app/src:${PYTHONPATH}"

# 入口点
CMD ["python", "src/main.py"]

ModuleNotFoundError: No module named '_speedup'

python setup.py build_ext --inplace

# 启用惰性导入
import sys
sys.set_lazy_imports(True)

# 导入仅在实际使用时发生
import heavy_module  # 不会立即加载

def use_module():
    heavy_module.compute()  # 首次使用时加载

# 延迟解析类型提示
from __future__ import annotations

class User:
    def __init__(self, name: str):
        self.name = name
    
    def merge(self, other: User) -> User:  # 不需要提前导入User
        return User(f"{self.name}+{other.name}")