Scrapy 安装指南：Python 版本要求、conda/pip 安装方式、可选 extras 与平台特定配置全解

本文基于 Scrapy 官方安装文档（docs/intro/install.rst）并结合当前仓库的 pyproject.toml 依赖定义展开，覆盖 Scrapy 对 Python 版本的要求、conda 与 pip 两种安装路径、虚拟环境使用建议、全部可选 extras 及其对应功能、Windows / Ubuntu / macOS / PyPy 四大平台的安装细节，以及一个高频故障（pyOpenSSL 与 Twisted 的 TLS 兼容性错误）的排查方法。读完后你可以完成一次干净、可复现的 Scrapy 安装，并能针对各平台常见的编译依赖问题对症处理。

一、支持的 Python 版本：3.10+，CPython 或 PyPy

Scrapy 要求 Python 3.10 及以上版本，支持 CPython（默认实现）和 PyPy 两种解释器。这一点在当前仓库的构建配置中有明确对应：

• pyproject.toml 中声明 requires-python = ">=3.10"；
• 其 classifiers 列表进一步标明了受支持的 CPython 实现（3.10–3.15）以及 CPython、PyPy 两种实现；
• 当前仓库版本为 2.18.0（见 scrapy/VERSION 与 pyproject.toml 的 bumpversion.current_version）。

因此安装前先确认 Python 版本：

python3 --version

二、安装 Scrapy：conda 或 pip

官方给出两条等价的安装路径。

2.1 使用 conda（conda-forge 渠道）

如果已在用 Anaconda 或 Miniconda，推荐直接从 conda-forge 渠道安装，它在 Linux、Windows、macOS 上都提供最新的二进制包，可绕开多数编译问题：

conda install -c conda-forge scrapy

2.2 使用 pip（从 PyPI 安装）

熟悉 Python 包管理的话，也可以直接从 PyPI 安装 Scrapy 及其全部依赖：

pip install Scrapy

官方强烈建议将 Scrapy 安装在一个专用的虚拟环境中，避免与系统已装的包发生版本冲突。另外要注意：在某些操作系统上，这条命令可能需要先解决 Scrapy 依赖的编译问题（例如缺少 C 编译头文件），具体请看下文各平台的安装说明。

2.3 Scrapy 的核心依赖构成

Scrapy 主体是纯 Python 代码，但依赖若干关键 Python 包，其中几个带有 C 扩展、是安装问题的主要来源：

依赖包	作用
lxml	高效的 XML/HTML 解析器
parsel	构建在 lxml 之上的 HTML/XML 数据抽取库
w3lib	处理 URL 与网页编码的多用途工具库
twisted	异步网络框架（Scrapy 引擎的基石）
cryptography、pyOpenSSL	处理网络层安全（TLS 等）需求

从 pyproject.toml 可以看到当前版本对这些依赖的精确下限：Twisted>=21.7.0、cryptography>=41.0.5、lxml>=4.6.4、parsel>=1.5.0、pyOpenSSL>=24.3.0、w3lib>=2.1.1，以及 itemadapter、itemloaders、protego、tldextract 等。其中有几个值得注意的平台条件依赖：

• PyDispatcher>=2.0.5 仅在 CPython 下安装，PyPyDispatcher>=2.1.0 仅在 PyPy 下安装（二者都是 Twisted signal 机制的信号分发后端）；
• brotli 用于 CPython，而 PyPy 下改用 brotlicffi；
• backports.zstd 仅在 Python 3.14 以下版本安装（3.14 起标准库自带 zstd 支持）。

上表中的 lxml、cryptography 等包本身还可能依赖非 Python 的 C 库（libxml2、libxslt、OpenSSL 等），这就是下文各平台说明要求先装系统级依赖的原因。

三、使用虚拟环境（官方推荐做法）

官方 TL;DR 一句话：在所有平台上，都建议把 Scrapy 装进虚拟环境。

Python 包可以装在全局（系统级）或用户级，但官方不推荐系统级安装 Scrapy——它可能与系统已装的包冲突，进而破坏系统工具与脚本。使用 venv 虚拟环境（Python 标准库模块）可以：

• 避免与系统包互相干扰；
• 使用 pip 正常安装，无需 sudo 等提权操作。

典型的建环境 + 安装流程：

python3 -m venv scrapy-env
source scrapy-env/bin/activate   # Windows 下为 scrapy-env\Scripts\activate
pip install scrapy

创建虚拟环境后，就可以在其中用 pip 安装 Scrapy，方式与其他 Python 包完全相同；非 Python 依赖（C 库）则需按平台说明先行安装。

四、可选 extras：按需启用扩展功能

Scrapy 提供可选 extras（Python 依赖规范中的 extras 机制），通过方括号在 pip install 时列出，即可一并安装对应依赖以启用特定功能：

pip install scrapy[s3,images]

当前仓库 pyproject.toml 中定义的 extras 与官方文档表格一致，完整清单如下（含实际安装的底层包）：

Extra	提供的功能	底层依赖（源自 pyproject.toml）
bpython	bpython 交互 shell	bpython>=0.7.1
gcs	Feed 导出与媒体管道写入 Google Cloud Storage	google-cloud-storage>=1.29.0
httpx	httpx 下载处理器，含 HTTP/2 与 SOCKS 代理支持	httpx2[http2,socks]>=2.0.0
images	图片管道（Images pipeline）	Pillow>=8.3.2
ipython	IPython 交互 shell	ipython>=8.15.0
ptpython	ptpython 交互 shell	ptpython>=3.0.23
robotparser	使用 robotexclusionrulesparser 解析 robots.txt	robotexclusionrulesparser>=1.6.2
s3	Amazon S3 存储：用于 Feed 导出、媒体管道与 s3:// 下载	boto3>=1.20.0
twisted-http2	Twisted 的 HTTP/2 下载处理器	Twisted[http2]>=21.7.0
uvloop	uvloop 高性能事件循环（仅非 Windows、非 PyPy 环境安装）	uvloop>=0.16.0（带 platform_system != 'Windows' and implementation_name != 'pypy' 条件）

例如需要 S3 存储 + 图片管道时：

pip install "scrapy[s3,images]"

五、平台特定安装说明

5.1 Windows

虽然可以用 pip 在 Windows 上装 Scrapy，但官方推荐安装 Anaconda 或 Miniconda 后使用 conda-forge 渠道的包，可避开绝大多数安装问题：

conda install -c conda-forge scrapy

如果坚持用 pip，需要注意：

警告：pip 安装方式要求系统中有 "Microsoft Visual C++" 构建工具来编译部分 Scrapy 依赖，占用的磁盘空间远多于 Anaconda 方案。

使用 pip 的步骤：

1. 下载并运行 Microsoft C++ Build Tools 安装 Visual Studio Installer；
2. 打开 Visual Studio Installer；
3. 在 Workloads 区域勾选 C++ build tools；
4. 检查安装详情，确保以下可选组件已勾选：
   • MSVC（例如 MSVC v142 - VS 2019 C++ x64/x86 build tools (v14.23)）
   • Windows SDK（例如 Windows 10 SDK (10.0.18362.0)）
5. 安装 Visual Studio Build Tools。

完成后即可回到上文用 pip install Scrapy 完成安装。

5.2 Ubuntu 14.04 及以上

Scrapy 与较新的 Ubuntu 发行版兼容（基于较新的 lxml、twisted、pyOpenSSL 版本测试），理论上也能支持 Ubuntu 14.04 等旧版本，但旧版本的 TLS 连接可能存在隐患。

不要使用 Ubuntu 仓库自带的 python-scrapy 包——它们通常过旧，且难以跟上 Scrapy 最新发布的节奏。

在 Ubuntu（及 Ubuntu 系）系统上，先用 apt 安装 C 依赖：

sudo apt-get install python3 python3-dev python3-pip libxml2-dev libxslt1-dev zlib1g-dev libffi-dev libssl-dev

各包用途：

• python3-dev、zlib1g-dev、libxml2-dev、libxslt1-dev → lxml 编译所需；
• libssl-dev、libffi-dev → cryptography 编译所需。

之后进入虚拟环境安装：

pip install scrapy

注：同样的非 Python 依赖可用于 Debian Jessie (8.0) 及以上系统。

5.3 macOS

编译 Scrapy 的依赖需要 C 编译器与开发头文件，在 macOS 上通常由 Apple 的 Xcode 命令行工具提供：

xcode-select --install

此外，macOS 系统 Python 存在一个已知的 pip 问题（pip 无法安全更新系统包），处理方式是：

• *（推荐）*不要使用系统 Python。安装一个不冲突的新 Python，使用 Homebrew：

  1. 按 Homebrew 官方说明安装 Homebrew；

  2. 更新 PATH，让 Homebrew 的包优先于系统包（zsh 用户把 .bashrc 换成 .zshrc）：

     echo "export PATH=/usr/local/bin:/usr/local/sbin:$PATH" >> ~/.bashrc
     source ~/.bashrc
     

  3. 安装 Python：

     brew install python
     

• *（可选）*把 Scrapy 装进 Python 虚拟环境——这既是对该 macOS 问题的规避手段，也是管理依赖的良好实践，可与上一条方法叠加使用。

完成上述任一规避后，即可正常安装：

pip install Scrapy

5.4 PyPy

官方建议使用最新版 PyPy；PyPy3 目前仅在 Linux 上做过安装测试。

由于多数 Scrapy 依赖只提供 CPython 的二进制 wheel 而没有 PyPy 版本，安装时会现场编译这些依赖。要点：

• macOS + PyPy：很可能遇到编译 cryptography 的失败，解决方案是 brew install openssl，再按该命令输出的提示 export 相关环境变量（只在安装 Scrapy 时需要）；
• Linux + PyPy：除安装构建依赖外没有特殊问题；
• Windows + PyPy：未做测试。

安装后运行 scrapy bench 验证安装是否正确。从源码看，scrapy/commands/bench.py 会启动内置基准服务器（scrapy/utils/benchserver.py）并驱动一个抓取 100000 个链接的 _BenchSpider，是覆盖 Scrapy 核心请求/响应链路的快速自检。如果该命令报出类似：

TypeError: ... got 2 unexpected keyword arguments

则说明 PyPyDispatcher 依赖未安装，执行：

pip install 'PyPyDispatcher>=2.1.0'

即可修复。这一点与 pyproject.toml 中 PyPyDispatcher 的条件依赖声明相互印证。

六、故障排查

AttributeError: 'module' object has no attribute 'OP_NO_TLSv1_1'

安装或升级 Scrapy、Twisted、pyOpenSSL 之后，可能出现如下异常：

[…]
  File "[…]/site-packages/twisted/protocols/tls.py", line 63, in <module>
    from twisted.internet._sslverify import _setAcceptableProtocols
  File "[…]/site-packages/twisted/internet/_sslverify.py", line 38, in <module>
    TLSVersion.TLSv1_1: SSL.OP_NO_TLSv1_1,
AttributeError: 'module' object has no attribute 'OP_NO_TLSv1_1'

原因：你的系统或虚拟环境中的 pyOpenSSL 版本，与当前 Twisted 版本所支持的版本不匹配。

修复方法：带 tls extra 重新安装 Twisted，让 pip 解决出相互兼容的版本组合：

pip install twisted[tls]

七、安装完成后

• 在虚拟环境内执行 scrapy bench，确认核心链路（下载、响应、链接抽取）工作正常；
• 如项目需要特定 extras（s3、gcs、httpx、images、twisted-http2、uvloop 等），按上文第四节的写法追加方括号安装；
• 若后续运行 scrapy shell 希望使用 IPython/bpython/ptpython，对应安装 ipython、bpython、ptpython extras；
• 更完整的版本演进历史可参考仓库内的 NEWS 文件。

适用前提与限制小结：本文以当前仓库（Scrapy 2.18.0，要求 Python ≥ 3.10）为准；Ubuntu/Debian 的 apt 包名基于文档所述版本，更新的大发行版上包名与仓库地址可能不同；PyPy 方案仅 Linux 经过官方测试，Windows + PyPy 组合不做保证。