Astropy 安装指南：从隔离环境搭建到源码构建与每日开发版

• 科学计算
• 科研
• 数据分析

本篇指南以 Astropy 官方安装文档 docs/install.rst 为核心脉络，完整讲解如何从零搭建隔离的 Python 环境、通过pip/conda安装 Astropy 及其依赖矩阵、验证安装、从源码构建，以及安装 nightly 开发版。读完本文，你将掌握一套可复现、可排查的 Astropy 环境搭建方案，并理解pip与conda两种包管理方式各自的适用场景与注意事项。

概览：第一步永远是隔离环境

安装 Astropy 的第一步，是确保你拥有一个与系统 Python 完全隔离的 Python 环境。这一点至关重要：Astropy 依赖众多（NumPy、PyERFA、PyYAML、packaging 等），如果直接把依赖装进系统 Python，很容易因为版本冲突意外破坏系统环境。因此官方安装文档 docs/install.rst 开篇就强调"隔离"，并将这条原则贯穿始终。

本安装指南官方推荐使用由miniforge提供的conda包管理器。选择它的理由很直接：

• 流行且对所有平台（Linux / macOS / Windows）支持良好；
• 安装和上手简单，对新用户友好；
• 便于安装最新版本的 Python（在 docs/development/quickstart.rst 的开发环境章节中同样强调了"便于安装不同 Python 版本以用于测试"这一点）。

如果你已经拥有一个基于miniforge的 Python 环境，可以直接跳到下面的「安装 Astropy」一节。

对于更有经验的用户，备选方案是使用 Python 标准库自带的venv模块等虚拟环境管理器。社区有大量资料可以帮你完成这类环境的搭建，原则相同：环境必须与系统 Python 隔离。

注意：不建议与 Anaconda / miniconda 的 defaults 通道混用

官方明确不推荐在已有的miniconda或Anaconda Python发行版中使用 Astropy：Anaconda Inc. 在defaults通道提供的 astropy 包可能版本过旧，且这些发行版在大规模组织内使用可能需要商业许可。请按本文所述使用miniforge（其默认远程软件源为社区主导的conda-forge通道）。

环境就绪后，你可以用pip或conda安装 Astropy。官方文档选择以pip为主进行讲解，因为用pip安装可选依赖更简单；当然，完全可以用conda完成同样的工作。

安装 miniforge

安装 Python 的第一步是安装miniforge。它会为你提供conda包管理器，并且默认把远程软件仓库指向社区主导的conda-forge通道。

安装完成后，在一个新终端（Windows 下为miniforge Prompt）中运行以下命令验证安装是否成功：

conda list

如果命令能正常输出已安装的软件包列表，说明conda已就绪。注意 Windows 用户应始终使用miniforge Prompt（而非普通 PowerShell / CMD），以确保conda命令在 PATH 中可用。

创建 Python 环境

打开终端（UNIX 系系统）或 miniforge Prompt（Windows），创建并激活一个专用于 Astropy 的虚拟环境：

conda create --channel conda-forge --name astropy python conda activate astropy

参数说明：

• --channel conda-forge：显式指定从 conda-forge 通道拉取包，与 miniforge 默认配置一致，同时避免误用其他通道中可能过旧的 astropy 包；
• --name astropy：环境名称，可以改成任意你喜欢的名字；
• python：不指定具体版本时，conda 会安装当前可用的最新稳定版 Python。如果你想锁定版本（例如复现特定环境），可以写成python=3.12这样的形式。

创建完成后，环境立即处于激活状态。但请注意：以后每次打开新终端，都需要重新执行conda activate astropy才能进入该环境。这是 conda 环境的常见"陷阱"，也是新手最容易遗漏的一步。

安装 Astropy

使用pip或conda安装 Astropy 均受官方支持，两种方式都能正常工作。但有一个重要警告：

警告：在 conda 环境中混用安装方式有风险

一旦你用conda创建好基础 Python 环境，此后尽量固定使用同一种方法安装新包。conda无法感知用pip安装的包，在conda install时可能直接覆盖（overwrite）它们，导致环境状态不一致。

使用 pip 安装

要安装 Astropy 以及你所选择的依赖组合，运行以下命令之一：

python -m pip install astropy # 仅安装最小必需依赖 python -m pip install "astropy[recommended]" # 安装推荐依赖 python -m pip install "astropy[all]" # 安装全部可选依赖

三种安装档位的含义，在 pyproject.toml 中有精确定义：

• 默认（不带 extra）：只安装[project.dependencies]中声明的最小必需依赖——astropy-iers-data、configobj、numpy、packaging、pyerfa、PyYAML；
• [recommended]：在最小依赖之上追加scipy、matplotlib、narwhals，以启用更多模块功能与绘图能力；
• [all]：聚合recommended、ipython、pandas、jupyter以及全部剩余可选运行时依赖（h5py、pyarrow、beautifulsoup4、bleach、sortedcontainers、pytz、jplephem、mpmath、asdf-astropy、bottleneck、fsspec、s3fs、certifi、uncompresspy等）。

绝大多数情况下，pip会安装一个预编译好的 wheel 包，无需本地编译。只有在你使用非常规平台时，pip才会回退到从源码安装；此时机器上必须装有可用的 C 编译器，安装才能成功（详见下文「从源码构建」）。

警告：切勿使用sudo或任何提权方式安装

官方明确警告不要用sudo pip install安装 Astropy 或其他包。提权安装会把包写入系统目录、绕过环境隔离，还可能破坏系统级 Python，应当始终在激活的虚拟环境中以普通用户身份安装。

使用 conda 安装

安装 Astropy 及最小依赖集：

conda install --channel conda-forge astropy

安装推荐依赖（SciPy 与 Matplotlib）：

conda install --channel conda-forge scipy matplotlib

安装全部可选依赖：

conda install --channel conda-forge ipython jupyter dask h5py pyarrow \ beautifulsoup4 html5lib bleach pandas sortedcontainers pytz jplephem mpmath \ asdf-astropy bottleneck fsspec s3fs certifi

这一串包名与 pyproject.toml 中[all]分组（含jupyter、pandas分组）所覆盖的组件基本对应：jupyter/ipython用于 notebook 交互与Table.show_in_notebook，dask/fsspec/s3fs用于云端与大数据场景，pyarrow用于 Parquet 读写，h5py用于 HDF5 读写，pandas用于 DataFrame 互转，asdf-astropy用于可移植序列化等。若你的conda环境中已包含这些包，可跳过对应条目。

测试安装是否成功

安装完成后，可以用 Astropy 官方测试套件验证安装版本是否正常。参见仓库内 docs/development/testguide.rst 的「Running tests on an installed astropy」一节：

python -m pip install "astropy[test]" pytest --pyargs astropy

其中astropy[test]会安装测试所需依赖（pytest、coverage、hypothesis、pytest-xdist、pytest-doctestplus等，完整清单见 pyproject.toml 的[project.optional-dependencies].test），而--pyargs astropy会从已安装的包（而非源码目录）中发现并运行测试，因此这条命令应在任何非 Astropy 源码目录的位置执行。

依赖要求

严格必需依赖

Astropy 有以下严格必需的依赖（即不安装就无法导入）：

以上版本数字并非写死在文档里：docs/install.rst使用|minimum_xxx_version|占位符，由 docs/conf.py 在构建文档时动态读取 pyproject.toml 中声明的版本约束并自动替换。因此文档中展示的最低版本与实际包元数据永远保持一致。例如requires-python = ">=3.12"（见 pyproject.toml）直接决定了minimum_python_version的取值。同样地，min_versions是从包元数据的Requirement中逐个解析numpy、pyerfa、matplotlib、scipy、packaging、pyyaml、ipython、pyarrow、fsspec、s3fs、asdf-astropy的版本约束生成的。

特别推荐的依赖

以下依赖虽非必需，但官方特别推荐安装，它们为多个模块提供核心功能：

• SciPy（最低 1.13）：为多个模块的各种功能提供底层支持（如astropy.stats、astropy.convolution、astropy.modeling等）；
• Matplotlib（最低 3.8.4）：提供绘图功能，astropy.visualization在其基础上进行增强。

按功能划分的可选依赖

以下依赖仅在需要对应功能时才安装。Astropy 即使不装这些包也能正常导入，缺少它们只会让相应功能不可用：

• h5py：读写 HDF5 格式的astropy.table.Table；
• BeautifulSoup：从 HTML 文件读取Table；
• html5lib：配合 pandas 读取器从 HTML 文件读取Table；
• bleach：在Table的 HTML 写入器关闭 HTML 转义时用于文本净化（sanitize）；
• ipydatagrid：在 Jupyter notebook 中以backend="ipydatagrid"显示Table.show_in_notebook；
• xmllint：校验 VOTABLE XML 文件（注意：这是 Python 之外的命令行工具，需在系统层面安装，不属于 pip 包）；
• pandas：Table与 pandasDataFrame之间的互转；
• sortedcontainers：为Table提供更快的SCEngine索引引擎（某些情况下仍可能比默认索引引擎慢）；
• pytz：指定和转换时区；
• jplephem：获取太阳系天体的 JPL 星历（ephemeris）；
• setuptools：用于发现 entry points，从而将拟合器（fitter）注入astropy.modeling.fitting；
• mpmath：用于astropy.stats.poisson_conf_interval的'kraft-burrows-nousek'区间；
• asdf-astropy（最低 0.11.0）：将各种 Astropy 类序列化为可移植、分层、人类可读的表示；
• bottleneck：提升 sigma-clipping 等对含 NaN 数组做统计运算的功能性能；
• certifi：当 Python 无法定位系统上最新的根 CA 证书时，用于从 HTTPS 或 FTP+TLS 站点下载文件（通常已作为requests的依赖随大多数 Python 安装附带）；
• pyarrow（最低 16.0）：读写 Parquet 格式的Table；
• fsspec（最低 2023.4.0）：无需下载整个文件即可访问远程 FITS 文件的子集；
• s3fs（最低 2023.4.0）：访问托管在 AWS S3 云存储中的文件。

上述依赖在 pyproject.toml 的[all]分组中均有对应声明（并带各自的最低版本约束），与本列表一一对应。

测试专用依赖

以下包仅在运行测试时可选用：

• pytest-xdist：分布式（并行）测试；
• pytest-mpl：基于 Matplotlib 图件的测试比对；
• objgraph：仅在测试中用于检测引用泄漏（reference leaks）；
• IPython（最低 8.1.0）：测试Table的 notebook 界面；
• coverage：代码覆盖率测量；
• skyfield：测试太阳系坐标；
• sgp4：测试卫星位置；
• tox：自动化测试与文档构建。

在 pyproject.toml 中，test与test_all分组正是这些测试依赖的机器可读定义：astropy[test]提供基础测试框架，astropy[test_all]则额外聚合objgraph、skyfield、sgp4、array-api-strict、numpy-quaddtype以及astropy[all]。

从源码构建

如果你想基于源码构建 Astropy，官方建议遵循 docs/development/quickstart.rst 中contributing_environment一节描述的开发环境搭建流程。注意：你也可以直接从主仓库克隆，而不必从自己的 fork 克隆：

git clone https://github.com/astropy/astropy.git cd astropy

通常没有必要在本地构建文档——除非你在开发代码/文档，或者处于无网络环境——因为 Astropy 的稳定版、最新版和历史版本文档都托管在 docs.astropy.org 上。

源码构建的环境准备

从源码构建需要在系统中准备可用的 C 编译器（用于编译 Astropy 的 C 与 Cython 扩展）：

• Windows：需要安装 "Build Tools for Visual Studio"（注意不需要安装完整版 Visual Studio）；
• macOS：运行xcode-select --install安装命令行开发者工具；
• Linux：通常无需额外安装组件（系统自带的 GCC 即可）。

在 pyproject.toml 的[build-system]中可以确认构建后端的需求：setuptools+setuptools_scm（版本号从 git 派生）+cython+numpy+extension-helpers+pyerfa+configobj，构建后端为setuptools.build_meta。此外 setup.py 会通过extension_helpers.get_extensions()自动发现并注册各子包的 C/Cython 扩展模块，并为使用 NumPy C-API 的扩展强制指定NPY_2_0_API_VERSION。

推荐的做法是照搬 quickstart 的隔离开发环境流程：

conda create -n astropy-dev python graphviz conda activate astropy-dev python -m pip install --editable . --group dev_all

说明：

• graphviz是构建文档所需的系统级包；
• --editable .（可编辑安装）让源码改动即时生效；
• --group dev_all对应 pyproject.toml 中定义的 PEP 735 依赖组dev_all，它聚合了dev（含recommended、test、docs、typing四组）、dataframe、image_tests、astropy[test_all]与tox，一次性装齐构建、测试、文档与类型检查所需的一切。

构建完成后，验证导入与测试：

python -c 'import astropy; astropy.system_info()' pytest astropy/coordinates # 先跑单个子包 pytest # 或跑全部测试

测试源码构建

在源码检出（source checkout）中运行测试最简便的方式是使用tox（tox.ini 定义了丰富的测试环境矩阵）：

tox -e test-alldeps

test-alldeps环境会安装all与test两组可选依赖（见 tox.ini 的extras配置），覆盖"全部可选依赖 + 测试依赖"的组合。tox 矩阵中还包含test-recdeps（推荐依赖）、test-oldestdeps（所有直接依赖的最老支持版本，用于验证最低版本声明）、test-devdeps（各关键依赖的最新开发版）、test-cov（覆盖率）、test-mpl380（固定 Matplotlib 3.8.4）等环境，完整列表可运行tox -l -v查看。如果你希望对测试过程有更多控制，可以参考 docs/development/testguide.rst 中描述的pytest替代运行方式（例如pytest --pyargs astropy、pytest -n auto并行等）。

安装预构建的开发版（nightly）

大多数夜晚，Astropy 项目都会编译一份开发版快照（nightly）。如果你希望在不自行构建的前提下，针对开发版 Astropy 进行测试，可以安装这些快照。可用快照清单发布在 pypi.anaconda.org 的 astropy 仓库中。

使用pip安装 nightly 的命令：

python -m pip install --upgrade --extra-index-url https://pypi.anaconda.org/astropy/simple astropy --pre

这条命令的两个关键参数：

• --extra-index-url：额外指定一个 pip 软件源——pypi.anaconda.org上的astropy/simple索引，nightly 快照即存放于此；
• --pre：允许pip安装预发布版本（在此即.dev开发版）。

--upgrade则确保你拿到的是最新构建的快照。安装后，同样可以用上文「测试安装是否成功」中的方式（先python -m pip install "astropy[test]"，再在非源码目录运行pytest --pyargs astropy）验证该 nightly 版本是否正常。

小结：安装决策速查

核心要点可以归纳为三条：环境必须隔离（用 miniforge/conda 或 venv）、pip 与 conda 二选一并从一而终（不要混用导致覆盖）、按需选择依赖档位（最小 / 推荐 / 全部），并善用pytest --pyargs astropy对任何安装方式的结果进行独立验证。

• 科学计算
• 科研
• 数据分析