在Github Actions的Ubuntu_latest x64环境中运行Sphinx生成文档时遭遇ImportError问题求助

Hey, I've run into similar dependency mismatch issues between local and CI environments before, so let's figure this out together. That circular import error with prompt_toolkit is almost definitely a version conflict between your Mac setup and the GitHub Actions Ubuntu runner. Here's what you can do to fix it:

1. Pin the prompt_toolkit version in your requirements.txt #

The error happens because the auto-resolved version of prompt_toolkit in the Ubuntu runner (with Python 3.8) is incompatible, leading to a circular import. Add an explicit version constraint to your requirements.txt to lock in a compatible release:

Sphinx>=3
sphinx_rtd_theme
sphinx-autodoc-typehints
GitPython
PyGithub
requests
ipykernel
ipywidgets
nbsphinx
recommonmark
prompt_toolkit>=3.0.30,<4

Version 3.x of prompt_toolkit is stable and compatible with Python 3.8, which is what the Ubuntu runner is using.

2. Align Python versions between local and CI #

Your local Mac is running the latest Python, but the GitHub Actions runner is using Python 3.8. This version gap can cause dependency resolution differences. Update your GitHub Actions workflow to use the same Python version as your local environment. For example, if you're on Python 3.10 locally:

steps:
  - name: Set up Python
    uses: actions/setup-python@v4
    with:
      python-version: '3.10'

This ensures dependencies install the same way they do on your Mac.

3. Clear cached dependencies in CI #

Sometimes old cached dependencies in GitHub Actions can cause conflicts. When installing requirements, use the --no-cache-dir flag to avoid using stale packages:

pip install --no-cache-dir -r requirements.txt

You can also add a step to clean up any existing cache if your workflow uses caching for Python dependencies.

4. Compare dependency trees #

To confirm the version mismatch, run pip freeze > local_deps.txt on your Mac, then in the GitHub Actions runner, run pip freeze > ci_deps.txt and compare the two files. Look specifically for prompt_toolkit and related packages—this will highlight exactly which versions are causing the conflict.

Why this works locally but not in CI #

Your Mac's newer Python version likely pulls in a compatible prompt_toolkit version automatically, while the older Python 3.8 on Ubuntu resolves to a version that has the circular import bug. By pinning the version and aligning Python versions, you eliminate this environment mismatch.

内容的提问来源于stack exchange，提问作者esocrats