【Docker设置】在 Docker 容器中运行 Python 项目时解决 `ModuleNotFoundError: No module named src` 问题

原创已于 2026-01-09 09:26:38 修改 · 537 阅读

16 ·

CC 4.0 BY-SA版权

文章标签：

#docker #python #容器

于 2026-01-09 09:26:07 首次发布

Docker 专栏收录该内容

2 篇文章

订阅专栏

很多开发者在将 Python 项目迁移到 Docker 容器运行时，都会遇到类似报错：

ModuleNotFoundError: No module named 'src'

这篇文章将帮你分析原因，并提供多种可行解决方案，让你的项目在容器中顺利运行。

一、问题背景

1.1 项目目录示例

假设我们的项目结构如下：

project_root/
├── src/
│   ├── video_downloader.py
│   └── utils.py
├── scripts/
│   └── run.py
└── requirements.txt

在 scripts/run.py 中，我们可能有如下导入：

from src.video_downloader import download_video

在这里插入图片描述

1.2 问题现象

在本地运行可能没有问题：

python scripts/run.py

但是在 Docker 容器中执行：

python scripts/run.py

可能会报错：

ModuleNotFoundError: No module named 'src'

1.3 问题原因

当 Python 执行 import 语句时，会按照 模块搜索路径（sys.path）顺序查找模块：

(1) 当前工作目录（Current Working Directory）

Python 会首先查找当前运行脚本所在的目录。

例如，如果你在容器中运行：
```
python scripts/run.py
```
此时的当前工作目录可能是 /workspace 而不是项目根目录 /workspace/project_root，Python 就找不到 src。

(2) 环境变量 PYTHONPATH

如果设置了 PYTHONPATH，Python 会将其中的路径加入搜索路径。
容器中通常没有预先设置 PYTHONPATH，所以项目根目录不会自动被包含。

(3) Python 自带库路径（Standard Library）

Python 会搜索安装目录下的标准库和 site-packages（第三方库）。
这个路径只包含 Python 内置模块和已安装的第三方包，与项目代码目录无关。

1.4 为什么容器里特别容易出错？

工作目录不固定：在本地，你可能在项目根目录运行脚本，一切正常；但在容器里，你执行脚本时默认工作目录可能是 / 或 /workspace，Python 无法找到相对路径下的 src。
缺少 PYTHONPATH：容器里环境干净，没有像本地开发环境那样配置 PYTHONPATH。
模块未安装：如果你尝试直接 import 项目内部模块而不是第三方包，也会出现找不到的情况。

二、解决方案

2.1 方法 A：临时 export PYTHONPATH

在容器 shell 中运行：

export PYTHONPATH=/workspace/project_root:$PYTHONPATH
python scripts/run.py

其中/workspace/project_root 替换为项目在容器中的路径

优点：快速临时解决
缺点：只在当前 shell 会话有效

2.2 方法 B：一行命令直接运行

可以在同一行命令中执行：

PYTHONPATH=/workspace/project_root python scripts/run.py

优点：
- 一次性执行，不影响其他命令
- 适合 CI/CD 或批量任务执行

2.3 方法 C：在 Dockerfile 中设置环境变量（永久生效）

在 Dockerfile 中加：

ENV PYTHONPATH=/workspace/project_root:$PYTHONPATH

或者在启动脚本里：

export PYTHONPATH=/workspace/project_root:$PYTHONPATH
python scripts/run.py

优点：容器每次启动都生效
缺点：需要修改 Dockerfile 或启动脚本

2.4 方法 D：在代码中动态添加路径

在 scripts/run.py 顶部加入：

import sys
from pathlib import Path

# 动态添加项目根目录到 sys.path
project_root = Path(__file__).parent.parent
sys.path.insert(0, str(project_root))

(1) 代码解析

import sys
- sys 模块是 Python 内置模块，其中 sys.path 是一个列表，记录 Python 的模块搜索路径。
- 当 Python 执行 import 时，会按照 sys.path 中的顺序查找模块。
from pathlib import Path
- pathlib 是 Python 3.4+ 的标准库，用于处理文件路径，语法更直观、跨平台。
- Path(__file__) 表示当前 Python 脚本的路径（包括文件名）。
project_root = Path(__file__).parent.parent
- Path(__file__).parent 是当前脚本所在目录（即 scripts/）。
- 再 .parent 就是项目根目录（即 project_root/）。
- 这样可以动态获取项目根目录，无论脚本从哪里执行，都能正确定位。
sys.path.insert(0, str(project_root))
- 将项目根目录转换成字符串路径，并插入到 sys.path 的第一个位置。
- 为什么插入到第一个位置？
  
  Python 会按顺序搜索 sys.path，放在第一个位置可以优先找到项目内部模块，避免和同名的标准库或第三方库冲突。

(2) 优缺点

优点
- 代码自包含：无需依赖外部环境变量（如 PYTHONPATH）
- 跨平台：使用 pathlib，可在 Linux、Windows、Mac 等系统上运行
缺点
- 依赖路径结构：如果项目结构改变，parent.parent 可能需要调整
- 不够透明：其他开发者可能需要看这段代码才能理解模块路径的来源

三、方案对比与总结

3.1 方法对比

方法	使用场景	优缺点
export + python	临时调试	简单快速，但只在当前 shell 会话有效
PYTHONPATH=… python	一次性执行	不影响其他命令，适合 CI/CD
Dockerfile ENV	容器永久生效	自动生效，但需修改 Dockerfile
sys.path.insert	跨平台代码自包含	灵活，但依赖代码路径结构