包与环境

SteelPython 像 CPython 一样使用 pip 和 venv，并从同一个地方——Python Package Index——安装相同的包。如果你熟悉 python -m pip 和 python -m venv，那么本页的内容你已经知道了；本页主要说明需要预期的情况。

安装包

spy -m pip install requests
spy -m pip install "pandas>=2" matplotlib
spy -m pip install -r requirements.txt
spy -m pip list
spy -m pip uninstall requests

pip 文档中的所有内容都适用：需求文件、约束、--index-url 和 --extra-index-url、pip download、pip wheel、代理（HTTPS_PROXY）以及证书（--cert、PIP_CERT；默认使用 Windows 证书存储）。

为自己安装

当 SteelPython 为机器上的所有用户安装时，没有管理员权限就无法写入它自己的 site-packages 文件夹。与 CPython 一样，pip 此时会改为安装到你的用户级文件夹 %APPDATA%\SteelPython\Python312\site-packages 中，并给出提示（“Defaulting to user installation because normal site-packages is not writeable”）；spy -m pip install --user ... 会显式要求使用该文件夹。这些包在你运行的每个 spy 中都可用。它们安装的命令位于 %APPDATA%\SteelPython\Python312\Scripts：请将该文件夹添加到 PATH，或通过 spy 运行它们，例如 spy -m IPython。若要为所有人安装，请在管理员终端中运行 pip。使用虚拟环境则可以完全避免这个问题。

二进制 wheel

SteelPython 可以运行 CPython 3.12 的编译扩展模块，因此 pip 安装的是 CPython 3.12 所用的同一批 wheel：PyPI 上的 cp312-win_amd64 和 abi3 wheel。numpy、pandas、scipy、scikit-learn、matplotlib、pyarrow、polars、duckdb、lxml、cryptography、pydantic、orjson 等包几秒钟即可安装完毕，无需编译任何东西，与 CPython 完全相同。

已知可以正常使用的包包括：numpy、pandas、scipy、scikit-learn、statsmodels、seaborn、matplotlib、PyTorch、Keras、transformers、numba、polars、pyarrow、duckdb、streamlit、Flask、FastAPI（配合 uvicorn）、Django、SQLAlchemy、requests、httpx、aiohttp、pydantic、cryptography、lxml、Pillow、grpcio、protobuf、greenlet 和 gevent、pytest、mypy 以及 black。

在 GPU 上运行 PyTorch

PyTorch 的 CUDA 版本来自 PyTorch 自己的索引；请按照其 Get Started 页面的说明安装，只需把 python 换成 spy：

spy -m pip install torch --index-url https://download.pytorch.org/whl/cu128
spy -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

这些 wheel 超过 2 GB；pip 会照常下载并缓存它们。

虚拟环境

像使用 CPython 时一样，为每个项目创建独立的环境（venv 文档）：

spy -m venv .venv
.venv\Scripts\activate
spy -m pip install -r requirements.txt
spy main.py
deactivate

在 PowerShell 中，请使用 .venv\Scripts\Activate.ps1 激活。环境在 Scripts\ 中有自己的 spy.exe，在 Lib\site-packages 中存放自己的包；不激活时，可以直接运行 .venv\Scripts\spy.exe。包安装的命令（pytest、black、streamlit 等）也会放在 Scripts\ 中，环境激活后即可按名称直接使用。

Misp 和 Spy Notebook 会找到项目文件夹中的环境（.venv、venv、env），也可以为你创建一个带有 pip 的环境。

由 SteelPython 创建的环境属于 SteelPython：由 CPython 创建的 .venv 不能被 spy 使用，反之亦然。请根据同一个 requirements.txt 另外创建一个环境。

从源代码构建包

有些包没有适用于 Windows 的 wheel，或者你可能想自己构建一个（pip install --no-binary，或你自己带有 C 代码的包）。与 Windows 上的 CPython 一样，这需要 C 编译器：请安装 Microsoft C++ Build Tools（Desktop development with C++ 工作负载）。SteelPython 自带构建所需的头文件和库（位于 spy.exe 旁边的 Include\ 和 libs\），setuptools 等构建后端会在查找 CPython 头文件和库的位置找到它们。编写扩展通过一个小示例完整演示了这一过程。

纯 Python 编写的包永远不需要编译器。

当某个包无法使用时

PyPI 上的大多数包都可以使用，但有些包可能依赖 SteelPython 所没有的东西：

Tk：任何导入 tkinter 的包（某些绘图后端、简单的 GUI 辅助工具）。对于 matplotlib，请使用非 Tk 后端：用 MPLBACKEND=Agg 将图形保存到文件，或在 Spy Notebook 中显示它们。
CPython 内部结构：直接读取解释器结构、而不是通过 C API 访问的包（某些在原生代码中检查帧的性能分析器和调试器、字节码重写工具），可能无法导入或行为异常。
引用计数的时机：其测试或逻辑期望对象在最后一个引用消失时就被释放的包（请参阅与 CPython 的差异）。

如果某个包无法使用，错误信息通常会说明原因。欢迎将行为异常的包报告至 contact@methodox.io。