{
  "id": "pip/error-from-pip-subprocess-to-build-wheel-with-missing-cython-header",
  "signature": "error: subprocess-exited-with-error: Cython.Compiler.Errors.CompileError: /path/to/file.pyx:1:0: 'header.h' not found",
  "signature_zh": "错误：子进程退出并出错：Cython.Compiler.Errors.CompileError: /path/to/file.pyx:1:0：未找到 'header.h'",
  "regex": "error: subprocess-exited-with-error: Cython\\.Compiler\\.Errors\\.CompileError: [^:]+:[0-9]+:[0-9]+: '[^']+' not found",
  "domain": "pip",
  "category": "build_error",
  "subcategory": null,
  "root_cause": "A Cython extension requires a C header file that is missing from the system's include path or the package's source distribution.",
  "root_cause_type": "generic",
  "root_cause_zh": "Cython 扩展需要一个 C 头文件，但该文件在系统的包含路径或包的源代码分发中缺失。",
  "versions": [
    {
      "version": "pip 21.3+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Python 3.8-3.12",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Cython 0.29.x, 3.0.x",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "setuptools 58+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Installing the missing header via pip (e.g., pip install libfoo-dev)",
      "why_fails": "Header files are usually provided by system packages (e.g., libfoo-dev on Debian/Ubuntu), not Python packages.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "Using --no-build-isolation to use the host environment's Cython version",
      "why_fails": "The error is about a missing header, not Cython version mismatch; build isolation does not affect header availability.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "Setting CFLAGS environment variable to point to a custom include path",
      "why_fails": "While this can work, many users incorrectly set the path or use wrong syntax; also requires knowing the exact header location.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Install the system development package: sudo apt-get install libfoo-dev  # Debian/Ubuntu, or sudo yum install libfoo-devel  # RHEL/CentOS",
      "success_rate": 0.9,
      "how": "Install the system development package: sudo apt-get install libfoo-dev  # Debian/Ubuntu, or sudo yum install libfoo-devel  # RHEL/CentOS",
      "condition": "",
      "sources": []
    },
    {
      "action": "pip install <package> --no-binary :all: --global-option='build_ext' --global-option='-I/path/to/include'",
      "success_rate": 0.75,
      "how": "pip install <package> --no-binary :all: --global-option='build_ext' --global-option='-I/path/to/include'",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a pre-built wheel from an alternative index: pip install <package> --only-binary :all: -i https://download.pytorch.org/whl/cpu  # Example for PyTorch with CPU-only",
      "success_rate": 0.8,
      "how": "Use a pre-built wheel from an alternative index: pip install <package> --only-binary :all: -i https://download.pytorch.org/whl/cpu  # Example for PyTorch with CPU-only",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "安装系统开发包：sudo apt-get install libfoo-dev  # Debian/Ubuntu，或 sudo yum install libfoo-devel  # RHEL/CentOS",
    "pip install <包名> --no-binary :all: --global-option='build_ext' --global-option='-I/path/to/include'",
    "使用来自替代索引的预构建 wheel：pip install <包名> --only-binary :all: -i https://download.pytorch.org/whl/cpu  # PyTorch CPU 版示例"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://cython.readthedocs.io/en/latest/src/userguide/source_files_and_compilation.html",
  "official_doc_section": null,
  "error_code": "error",
  "verification_tier": "ai_generated",
  "confidence": 0.86,
  "fix_success_rate": 0.82,
  "resolvable": "partial",
  "first_seen": "2024-03-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}