Jenkins使用withPythonEnv插件创建virtualenv报错如何解决

云原生阿岚

2026-9-24

报错根因

该报错是系统预装的Python版本缺失ensurepip模块导致的：大多数Linux发行版会移除系统Python的ensurepip模块，避免和系统包管理器管理的pip包冲突，因此插件调用ensurepip初始化虚拟环境时会返回非零退出码。

解决方案

按优先级尝试以下操作即可解决问题：

优先安装对应Python版本的venv和pip系统包
所有你用到的Python3.6/3.7/3.8/3.9版本都需要安装对应系统包，以Python3.8为例：
Debian/Ubuntu系系统执行命令：
```
apt update && apt install -y python3.8-venv python3.8-pip
```
RHEL/CentOS/Fedora系系统执行命令：
```
dnf install -y python38-venv python38-pip
```
安装完成后重新运行构建，绝大多数场景下问题会直接解决。

若安装系统包后仍报错，修改Pipeline配置跳过ensurepip逻辑
给withPythonEnv传入extraArgs参数禁用默认的pip初始化逻辑，再用系统级对应版本pip给虚拟环境安装pip即可，修改后的Pipeline示例如下：

stage ('Unit Test'){
    steps {
        // 新增extraArgs参数，创建虚拟环境时跳过ensurepip初始化
        withPythonEnv('/usr/bin/python3.8', extraArgs: '--without-pip') {
            script{
                sh """
                    pwd
                    env
                    python --version
                    // 用系统预装的pip3.8给当前虚拟环境安装pip
                    /usr/bin/pip3.8 install --prefix=$VIRTUAL_ENV pip
                    pip install --upgrade pip
                    pip install -r requirements-test.txt
                    python -m pytest foo/tests/ --cov foo --cov-report=xml --junitxml=junit.xml
                """
            }
        }
    }
    post {
        always {
            script {
                junit "junit.xml"
            }
        }
    }
}