GitHub Actions中如何提前安装NumPy满足依赖构建需求？

DevOps 小满

2026-7-21

问题

我在GitHub上配置了一个使用pytest执行单元测试的工作流。requirements.txt中的某一依赖在其setup.py中使用numpy.distutils安装Fortran扩展，因此需要在安装其他依赖前先安装NumPy。

我的workflow.yaml文件内容如下：

name: unit_tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.8", "3.9", "3.10", "3.11"]
        os: [ubuntu-latest, windows-latest, macos-latest]
    steps:
    - uses: actions/checkout@v3
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
    - name: Installing Numpy
      run: |
        pip install pip --upgrade
        pip install numpy
    - name: Installing requirements
      run: |
        pip install flake8 pytest
        pip install -r requirements.txt
    - name: Lint with flake8
      run: |
        # stop the build if there are Python syntax errors or undefined names
        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
    - name: Test with pytest
      run: |
        pytest

目前，直到并包括“Installing Numpy”的所有步骤均执行成功：

Collecting numpy
  Downloading numpy-1.24.3-cp310-cp310-macosx_10_9_x86_64.whl (19.8 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 19.8/19.8 MB 11.0 MB/s eta 0:00:00
Installing collected packages: numpy
Successfully installed numpy-1.24.3

但“Installing requirements”步骤执行失败，报错信息如下：

× Getting requirements to build wheel did not run successfully.
  │ exit code: 1
  ╰─> [17 lines of output]
      Traceback (most recent call last):
        File "/Users/runner/hostedtoolcache/Python/3.10.11/x64/lib/python3.10/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 353, in <module>
          main()
        File "/Users/runner/hostedtoolcache/Python/3.10.11/x64/lib/python3.10/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 335, in main
          json_out['return_val'] = hook(**hook_input['kwargs'])
        File "/Users/runner/hostedtoolcache/Python/3.10.11/x64/lib/python3.10/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 118, in get_requires_for_build_wheel
          return hook(config_settings)
        File "/private/var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T/pip-build-env-67g_j2me/overlay/lib/python3.10/site-packages/setuptools/build_meta.py", line 341, in get_requires_for_build_wheel
          return self._get_build_requires(config_settings, requirements=['wheel'])
        File "/private/var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T/pip-build-env-67g_j2me/overlay/lib/python3.10/site-packages/setuptools/build_meta.py", line 323, in _get_build_requires
          self.run_setup()
        File "/private/var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T/pip-build-env-67g_j2me/overlay/lib/python3.10/site-packages/setuptools/build_meta.py", line 487, in run_setup
          super(_BuildMetaLegacyBackend,
        File "/private/var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T/pip-build-env-67g_j2me/overlay/lib/python3.10/site-packages/setuptools/build_meta.py", line 338, in run_setup
          exec(code, locals())
        File "<string>", line 5, in <module>
      ModuleNotFoundError: No module named 'numpy'
      [end of output]

该错误表明NumPy未被识别。所有Python版本和操作系统均出现此问题。我该如何确保安装其他依赖时NumPy已存在且可用？另外需要说明的是，NumPy也包含在requirements.txt中。

解决方案

问题根源在于pip在构建某些依赖的wheel时，会创建隔离的临时构建环境，提前安装的NumPy不在这个环境里，导致构建时找不到numpy模块。

可以通过以下两种方法解决：

方法1：禁用构建隔离

修改"Installing requirements"步骤的命令，添加--no-build-isolation参数，让pip直接使用当前环境已安装的包来构建依赖：

- name: Installing requirements
  run: |
    pip install flake8 pytest
    pip install --no-build-isolation -r requirements.txt

方法2：为构建环境预安装NumPy

如果你需要保留构建隔离，可以通过--config-settings参数指定构建环境提前安装numpy：

- name: Installing requirements
  run: |
    pip install flake8 pytest
    pip install --config-settings=setup-requires=numpy -r requirements.txt

或者，将numpy从requirements.txt中移除，先安装numpy再安装剩余依赖：

- name: Installing Numpy and requirements
  run: |
    pip install pip --upgrade
    pip install numpy
    pip install flake8 pytest
    pip install -r requirements.txt

GitHub Actions中如何提前安装NumPy满足依赖构建需求？

方法1：禁用构建隔离 #

方法2：为构建环境预安装NumPy #

推荐方案 #

方法1：禁用构建隔离

方法2：为构建环境预安装NumPy

推荐方案