环境与前提确认
快速核对当前系统与 Python 版本
在极简 Ubuntu 环境下排查“Python 模块找不到的问题”时，第一步是确认 Python 解释器的版本与路径，确保使用的是合适的版本进行安装与执行。通过以下命令获取关键信息：python3 --version、which python3，以及 python3 -c "import sys; print(sys.version)"。如果默认的 python 指向 python2，需要显式使用 python3 来安装与运行。为了后续步骤的一致性，记录 Python 路径 与当前环境名称。
另外，确认当前工作环境是否处在一个活跃的虚拟环境中。虚拟环境是隔离依赖的关键，有助于避免系统范围的冲突。观察 PATH 与 sys.path，确保后续操作在同一解释器下进行。
python3 --version
which python3
python3 -V
若系统中没有安装 pip，下一步需要安装它。可以先更新软件源，然后安装对应的包。
sudo apt-get update
sudo apt-get install -y python3-pip
搭建干净的执行环境
创建并激活虚拟环境
为避免系统范围的依赖冲突，建议在极简 Ubuntu 中优先使用虚拟环境来管理 Python 包。创建一个独立的虚拟环境并激活，能确保后续安装的模块只影响该环境。如下所示：
python3 -m venv ~/venv
source ~/venv/bin/activate
激活后，虚拟环境中的 pip 将独立于系统安装，确保后续安装不会污染全局环境。若需要退出虚拟环境，执行 deactivate。
deactivate
进入环境后，最好升级 pip、setuptools 与 wheel，以获得最新的软件打包与安装能力。
python -m pip install --upgrade pip setuptools wheel
解决模块找不到的常见原因
环境激活状态与路径检查
模块找不到的问题往往因为当前终端会话没有激活正确的虚拟环境，或解释器路径被切换导致的。请 再次确认当前使用的 Python 解释器、以及 sys.path 是否包含目标的 site-packages 目录。可以用以下命令查看：
python -m site
python -c "import sys; print(sys.path)"
在已激活的环境中，查看已安装的包列表以确认目标模块是否已经安装： pip list。若未安装则需要执行安装，若安装在不同的环境中，需要切换到正确的虚拟环境后再操作。
pip list
如果发现目标模块仍然无法导入，直接在当前环境中尝试安装它，使用 pip install，并尽量指定版本以避免兼容性问题：
pip install <模块名>==<版本号>
快速在极简Ubuntu中安装与优化
安装构建依赖与 pip
在极简系统中，很多带本地扩展的包需要编译，故需要安装编译工具与头文件。先安装基础依赖，再升级 Python 打包工具：
sudo apt-get update
sudo apt-get install -y build-essential libssl-dev libffi-dev python3-dev
python3 -m pip install --upgrade pip setuptools wheel
为了提高安装速度，可以临时指定镜像源，中国大陆用户常用清华镜像等。示例：
python3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <模块名>
若要对某个项目持续使用该镜像源，可以在全局或用户级创建配置：
mkdir -p ~/.config/pip
echo "[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple" > ~/.config/pip/pip.conf
使用本地镜像源提升效率
在极简环境中网络状况可能成为瓶颈，使用本地镜像源能显著提升下载、编译速度。请保持配置的一致性，确保 pip 使用的是镜像源地址，并在必要时加上 trusted-host 以避免证书交互问题。
python3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn <模块名>
处理带本地扩展的模块和依赖
安装系统依赖再安装 Python 包
带有本地扩展的包（如 numpy、pandas）往往需要 Fortran、BLAS、LAPACK 等底层库。先安装系统级依赖，再通过 pip 安装 Python 封装：
sudo apt-get install -y libblas-dev liblapack-dev libatlas-base-dev gfortran
python3 -m pip install numpy pandas
如果遇到编译问题，优先使用 wheel 形式的预编译包；可以通过强制使用二进制轮子来避免编译阶段：
python3 -m pip install --only-binary=:all: numpy
在某些环境中，仍需指定目标版本以确保与 Python 版本兼容，或使用虚拟环境内的镜像源实现稳定性。
python3 -m pip install numpy==1.23.5
若需要在一个项目中同时管理多个依赖，推荐使用 requirements.txt，并通过一条命令批量安装：
pip install -r requirements.txt
