Ubuntu 22.04 安装 Apache Hamilton 指南

在 Ubuntu 22.04 上从零安装 Apache Hamilton 的完整指南，覆盖版本选型、在线 pip 与离线 wheel 两种安装方案、extras 按需安装、升级降级与双包名混装排障、卸载清理，全部命令实测验证。

Apache HamiltonApacheApache Hamilton数据管道安装部署Ubuntu 22.042026/10/14

Ubuntu 22.04 安装 Apache Hamilton 指南

目标：在 Ubuntu 22.04 服务器上从零完成 Apache Hamilton 的安装与验证，覆盖版本选型、在线 pip 安装主方案、离线 wheel 安装备用方案、extras 按需安装、升级与降级、双包名混装排障以及卸载清理。全文命令均在 Ubuntu 22.04（Python 3.10.12）环境实测通过，安装版本为 apache-hamilton 1.90.0，所有回显逐字取自真实运行结果。

一、环境信息

本文全部命令与回显均在以下环境实测取得，复现时保持相近版本即可获得一致结果。

  • 操作系统：Ubuntu 22.04（x86_64）
  • Python：3.10.12（系统 pip 22.0.2，虚拟环境内升级至 pip 26.2.1）
  • Apache Hamilton：apache-hamilton 1.90.0（PyPI 新包名最新版，Apache-2.0 许可）
  • 验证用虚拟环境：/opt/venv-hamilton（在线安装）、/opt/venv-hamilton-offline（离线安装）
  • 网络代理：192.168.1.62:7897（访问 PyPI 缓慢或失败时启用）

先验证两条最关键的基础信息，确认操作系统自带的 Python 与 pip 可用：

python3 -V

输出：

Python 3.10.12

pip3 --version

输出：

pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)

安装完成后的最终验证命令（后文详述步骤）实测回显如下：

/opt/venv-hamilton/bin/python -c "from importlib.metadata import version; print(version('apache-hamilton'))"

输出：

1.90.0

二、前置条件

Apache Hamilton 是纯 Python 库，前置条件只有一条硬性门槛：Python 版本。PyPI 元数据实测要求 Requires-Python: <4,>=3.10.1，classifiers 覆盖 3.10 至 3.14；低于 3.10.1 的环境无法安装。前置清单如下：

前置项要求实测情况
操作系统Linux 即可，本文以 Ubuntu 22.04 为准通过
Python3.10.1 及以上、4 以下3.10.12 通过
pip随 python3-pip 提供，建议在虚拟环境内升级后使用系统自带 22.0.2，升级至 26.2.1
网络能访问 PyPI；缓慢时配置代理走代理后整包安装约 20 秒完成

对上表的解读：依赖门槛极低是 Hamilton 的安装优势——核心包只依赖 numpy、pandas、typing_extensions、typing_inspect 四项（见第四节 pip show 回显的 Requires 字段），不需要编译器、JDK 或外部服务。

Ubuntu 22.04 最小安装默认不带 venv 模块与 pip，先补齐基础环境：

apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y python3 python3-venv python3-pip

输出（实测节选，中段略）：

Get:1 http://archive.ubuntu.com/ubuntu jammy InRelease [270 kB]

完整输出较长：末段依次出现 Setting up python3-venv、Setting up libpython3.10-dev、Setting up python3-pip、Setting up python3-dev 等安装行，直至 Processing triggers for ca-certificates 后正常返回提示符。用第一节的两条命令（python3 -V、pip3 --version）确认前置就绪即可。

三、版本选型说明

Apache Hamilton 在 PyPI 上经历过一次包名迁移：历史包名 sf-hamilton（版本自 1.1.1 延续至今），现行包名 apache-hamilton（项目进入 Apache 软件基金会孵化后启用）。两个包名导入的 Python 包名都是 hamilton。先看两个包名各自名下的可用版本：

/opt/venv-hamilton/bin/pip index versions apache-hamilton

输出：

apache-hamilton (1.90.0)
Available versions: 1.90.0, 1.89.0
  INSTALLED: 1.90.0
  LATEST:    1.90.0

/opt/venv-hamilton/bin/pip index versions sf-hamilton

输出（完整，sf-hamilton 名下历史版本自 1.1.1 一直延续到 1.90.0）：

sf-hamilton (1.90.0)
Available versions: 1.90.0, 1.89.0, 1.88.0, 1.87.0, 1.86.1, 1.85.1, 1.85.0, 1.84.0, 1.83.3, 1.83.2, 1.83.1, 1.83.0, 1.82.0, 1.81.2, 1.81.1, 1.81.0, 1.80.0, 1.79.0, 1.78.0, 1.77.1, 1.77.0, 1.76.0, 1.75.1, 1.75.0, 1.74.0, 1.73.2, 1.73.1, 1.73.0, 1.72.1, 1.72.0, 1.71.0, 1.70.0, 1.69.0, 1.68.0, 1.67.0, 1.66.1, 1.66.0, 1.65.0, 1.64.1, 1.64.0, 1.63.0, 1.62.0, 1.61.0, 1.60.0, 1.59.1, 1.59.0, 1.58.0, 1.57.0, 1.56.0, 1.55.1, 1.55.0, 1.54.1, 1.54.0, 1.53.0, 1.52.0, 1.51.1, 1.51.0, 1.50.1, 1.49.2, 1.49.1, 1.49.0, 1.48.0, 1.47.0, 1.46.0, 1.45.0, 1.44.0, 1.43.1, 1.43.0, 1.42.0, 1.41.0, 1.40.1, 1.40.0, 1.39.1, 1.39.0, 1.38.1, 1.38.0, 1.37.1, 1.37.0, 1.36.0, 1.35.1, 1.35.0, 1.34.1, 1.34.0, 1.33.1, 1.33.0, 1.32.0, 1.31.0, 1.30.1, 1.30.0, 1.29.0, 1.28.0, 1.27.4, 1.27.3, 1.27.2, 1.27.1, 1.27.0, 1.26.5, 1.26.4, 1.26.3, 1.26.2, 1.26.1, 1.26.0, 1.25.0, 1.24.0, 1.23.2, 1.23.1, 1.23.0, 1.22.6, 1.22.5, 1.22.4, 1.22.3, 1.22.2, 1.22.1, 1.22.0, 1.21.2, 1.21.1, 1.21.0, 1.20.1, 1.20.0, 1.19.0, 1.18.0, 1.17.0, 1.16.0, 1.15.0, 1.14.1, 1.13.0, 1.12.0, 1.11.1, 1.11.0, 1.10.0, 1.9.0, 1.8.0, 1.7.1, 1.7.0, 1.6.0, 1.5.1, 1.5.0, 1.4.0, 1.3.0, 1.2.0, 1.1.1

⚠️ 重要发现：apache-hamilton 名下的 1.89.0 只有 sdist 源码包，且其内部元数据仍是旧名 sf-hamilton，pip 会以「包名不一致」为由拒绝安装（完整报错见 8.3 节实测）。需要 1.89.0 时只能通过旧包名 sf-hamilton==1.89.0 安装；更早的历史版本同理只能走 sf-hamilton。

PyPI 页面实测元数据（1.90.0）：wheel 文件 apache_hamilton-1.90.0-py3-none-any.whl（475 kB，上传于 Apr 26, 2026），Requires-Python: <4,>=3.10.1，classifiers 覆盖 Python 3.10 至 3.14，许可证为 Apache-2.0。版本选型建议归纳如下：

场景推荐安装写法说明
全新安装（推荐）pip install apache-hamilton装到最新 1.90.0，新包名是官方当前主推
需要 1.89.0pip install sf-hamilton==1.89.0apache-hamilton==1.89.0 实测被 pip 拒装
需要更早历史版本pip install sf-hamilton==1.50.0（示例）目标版本号以 pip index versions sf-hamilton 输出为准
生产环境多项目共存每个版本独立虚拟环境见 8.1 节与 8.3 节

四、方案 A：在线 pip 安装（主方案）

这是官方默认路径：虚拟环境隔离 + pip 从 PyPI 安装。分三步：建虚拟环境并升级 pip、安装、验证。

第一步，创建独立虚拟环境并升级 pip（系统自带的 pip 22.0.2 较旧，升级后 pip show 能显示更完整的元数据字段）：

python3 -m venv /opt/venv-hamilton && /opt/venv-hamilton/bin/pip install --upgrade pip

输出（实测节选）：

Installing collected packages: pip
  Attempting uninstall: pip
    Found existing installation: pip 22.0.2
    Uninstalling pip-22.0.2:
      Successfully uninstalled pip-22.0.2
Successfully installed pip-26.2.1

💡 说明：若直连 PyPI 下载缓慢（实测曾出现约 32.5 kB/s、numpy 的 16.8 MB 长时间未完成的情况），先设置代理再安装，实测配置代理后整包约 20 秒完成，代理配置方法见 8.2 节。

第二步，安装 apache-hamilton：

/opt/venv-hamilton/bin/pip install apache-hamilton

输出（完整）：

Collecting apache-hamilton
  Using cached apache_hamilton-1.90.0-py3-none-any.whl.metadata (22 kB)
Collecting numpy (from apache-hamilton)
  Using cached numpy-2.2.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (62 kB)
Collecting pandas (from apache-hamilton)
  Using cached pandas-2.3.3-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.metadata (91 kB)
Collecting typing_extensions>4.0.0 (from apache-hamilton)
  Using cached typing_extensions-4.16.0-py3-none-any.whl.metadata (3.3 kB)
Collecting typing_inspect (from apache-hamilton)
  Using cached typing_inspect-0.9.0-py3-none-any.whl.metadata (1.5 kB)
Collecting python-dateutil>=2.8.2 (from pandas->apache-hamilton)
  Using cached python_dateutil-2.9.0.post0-py2.py3-none-any.whl.metadata (8.4 kB)
Collecting pytz>=2020.1 (from pandas->apache-hamilton)
  Using cached pytz-2026.5-py2.py3-none-any.whl.metadata (22 kB)
Collecting tzdata>=2022.7 (from pandas->apache-hamilton)
  Using cached tzdata-2026.5-py2.py3-none-any.whl.metadata (1.4 kB)
Collecting six>=1.5 (from python-dateutil>=2.8.2->pandas->apache-hamilton)
  Using cached six-1.17.0-py2.py3-none-any.whl.metadata (1.7 kB)
Collecting mypy-extensions>=0.3.0 (from typing_inspect->apache-hamilton)
  Using cached mypy_extensions-1.1.0-py3-none-any.whl.metadata (1.1 kB)
Using cached apache_hamilton-1.90.0-py3-none-any.whl (475 kB)
Using cached typing_extensions-4.16.0-py3-none-any.whl (45 kB)
Using cached numpy-2.2.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (16.8 MB)
Downloading pandas-2.3.3-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (12.8 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 12.8/12.8 MB 40.8 MB/s  0:00:00
Downloading python_dateutil-2.9.0.post0-py2.py3-none-any.whl (229 kB)
Downloading pytz-2026.5-py2.py3-none-any.whl (506 kB)
Downloading six-1.17.0-py2.py3-none-any.whl (11 kB)
Downloading tzdata-2026.5-py2.py3-none-any.whl (347 kB)
Downloading typing_inspect-0.9.0-py3-none-any.whl (8.8 kB)
Downloading mypy_extensions-1.1.0-py3-none-any.whl (5.0 kB)
Installing collected packages: pytz, tzdata, typing_extensions, six, numpy, mypy-extensions, typing_inspect, python-dateutil, pandas, apache-hamilton

Successfully installed apache-hamilton-1.90.0 mypy-extensions-1.1.0 numpy-2.2.6 pandas-2.3.3 python-dateutil-2.9.0.post0 pytz-2026.5 six-1.17.0 typing_extensions-4.16.0 typing_inspect-0.9.0 tzdata-2026.5

从安装回显可以核对依赖清单：直接依赖为 numpy 2.2.6、pandas 2.3.3、typing_extensions 4.16.0、typing_inspect 0.9.0，另有 python-dateutil、pytz、tzdata、six、mypy_extensions 五项传递依赖，全部自动处理，无需手工干预。

第三步，双层验证——先看 pip 元数据，再看运行时版本：

/opt/venv-hamilton/bin/pip show apache-hamilton

输出（完整）：

Name: apache-hamilton
Version: 1.90.0
Summary: Apache Hamilton (incubating) is a lightweight Python library for directed acyclic graphs (DAGs) of transformations. Your DAG is **portable**; it runs anywhere Python runs, whether it's a script, notebook, Airflow pipeline, FastAPI server, etc. Your DAG is **expressive**; Apache Hamilton has extensive features to define and modify the execution of a DAG (e.g., data validation, experiment tracking, remote execution).
Home-page: https://www.tryhamilton.dev/
Author:
Author-email: Stefan Krawczyk <stefank@cs.stanford.edu>, Elijah ben Izzy <elijah@dagworks.io>
License-Expression: Apache-2.0
Location: /opt/venv-hamilton/lib/python3.10/site-packages
Requires: numpy, pandas, typing_extensions, typing_inspect
Required-by:

/opt/venv-hamilton/bin/python -c "import hamilton; print(hamilton.__version__)"

输出（注意：返回的是元组，不是字符串）：

(1, 90, 0)

💡 说明：hamilton.__version__ 返回元组 (1, 90, 0) 是当前版本的实际行为。需要字符串版本号时用标准库读元数据更稳妥：

/opt/venv-hamilton/bin/python -c "from importlib.metadata import version; print(version('apache-hamilton'))"

输出：

1.90.0

五、方案 B：离线 wheel 安装（内网/无外网服务器）

生产内网服务器通常无法直连 PyPI。做法是：在一台能联网的机器上用 pip download 把目标包与全部依赖的 wheel 收集到目录，再将该目录拷贝到目标机，用 --no-index --find-links 离线安装。实测分四步。

第一步，在联网机上收集 wheel（联网机同样用虚拟环境内的 pip 执行，保证 wheel 与目标机 Python 版本匹配）：

/opt/venv-hamilton/bin/pip download apache-hamilton -d /tmp/hamilton-wheels

输出（完整）：

Collecting apache-hamilton
  Using cached apache_hamilton-1.90.0-py3-none-any.whl.metadata (22 kB)
Collecting numpy (from apache-hamilton)
  Using cached numpy-2.2.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (62 kB)
Collecting pandas (from apache-hamilton)
  Using cached pandas-2.3.3-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.metadata (91 kB)
Collecting typing_extensions>4.0.0 (from apache-hamilton)
  Using cached typing_extensions-4.16.0-py3-none-any.whl.metadata (3.3 kB)
Collecting typing_inspect (from apache-hamilton)
  Using cached typing_inspect-0.9.0-py3-none-any.whl.metadata (1.5 kB)
Collecting python-dateutil>=2.8.2 (from pandas->apache-hamilton)
  Using cached python_dateutil-2.9.0.post0-py2.py3-none-any.whl.metadata (8.4 kB)
Collecting pytz>=2020.1 (from pandas->apache-hamilton)
  Using cached pytz-2026.5-py2.py3-none-any.whl.metadata (22 kB)
Collecting tzdata>=2022.7 (from pandas->apache-hamilton)
  Using cached tzdata-2026.5-py2.py3-none-any.whl.metadata (1.4 kB)
Collecting six>=1.5 (from python-dateutil>=2.8.2->pandas->apache-hamilton)
  Using cached six-1.17.0-py2.py3-none-any.whl.metadata (1.7 kB)
Collecting mypy-extensions>=0.3.0 (from typing_inspect->apache-hamilton)
  Using cached mypy_extensions-1.1.0-py3-none-any.whl.metadata (1.1 kB)
Using cached apache_hamilton-1.90.0-py3-none-any.whl (475 kB)
Using cached typing_extensions-4.16.0-py3-none-any.whl (45 kB)
Using cached numpy-2.2.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (16.8 MB)
Using cached pandas-2.3.3-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (12.8 MB)
Using cached python_dateutil-2.9.0.post0-py2.py3-none-any.whl (229 kB)
Using cached pytz-2026.5-py2.py3-none-any.whl (506 kB)
Using cached six-1.17.0-py2.py3-none-any.whl (11 kB)
Using cached tzdata-2026.5-py2.py3-none-any.whl (347 kB)
Using cached typing_inspect-0.9.0-py3-none-any.whl (8.8 kB)
Using cached mypy_extensions-1.1.0-py3-none-any.whl (5.0 kB)
Saved ./tmp/hamilton-wheels/apache_hamilton-1.90.0-py3-none-any.whl
Saved ./tmp/hamilton-wheels/typing_extensions-4.16.0-py3-none-any.whl
Saved ./tmp/hamilton-wheels/numpy-2.2.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Saved ./tmp/hamilton-wheels/pandas-2.3.3-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Saved ./tmp/hamilton-wheels/python_dateutil-2.9.0.post0-py2.py3-none-any.whl
Saved ./tmp/hamilton-wheels/pytz-2026.5-py2.py3-none-any.whl
Saved ./tmp/hamilton-wheels/six-1.17.0-py2.py3-none-any.whl
Saved ./tmp/hamilton-wheels/tzdata-2026.5-py2.py3-none-any.whl
Saved ./tmp/hamilton-wheels/typing_inspect-0.9.0-py3-none-any.whl
Saved ./tmp/hamilton-wheels/mypy_extensions-1.1.0-py3-none-any.whl
Successfully downloaded apache-hamilton typing_extensions numpy pandas python-dateutil pytz six tzdata typing_inspect mypy-extensions

第二步，核对下载产物（10 个 wheel，共约 30 MB，整目录拷贝到目标机即可）：

ls -la /tmp/hamilton-wheels

输出（完整）：

total 30500
drwxr-xr-x 2 root root     4096 Oct 14 13:01 .
drwxrwxrwt 1 root root     4096 Oct 14 13:01 ..
-rw-r--r-- 1 root root   475199 Oct 14 13:01 apache_hamilton-1.90.0-py3-none-any.whl
-rw-r--r-- 1 root root     4963 Oct 14 13:01 mypy_extensions-1.1.0-py3-none-any.whl
-rw-r--r-- 1 root root 16801050 Oct 14 13:01 numpy-2.2.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
-rw-r--r-- 1 root root 12769373 Oct 14 13:01 pandas-2.3.3-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
-rw-r--r-- 1 root root   229892 Oct 14 13:01 python_dateutil-2.9.0.post0-py2.py3-none-any.whl
-rw-r--r-- 1 root root   506342 Oct 14 13:01 pytz-2026.5-py2.py3-none-any.whl
-rw-r--r-- 1 root root    11050 Oct 14 13:01 six-1.17.0-py2.py3-none-any.whl
-rw-r--r-- 1 root root    45571 Oct 14 13:01 typing_extensions-4.16.0-py3-none-any.whl
-rw-r--r-- 1 root root     8827 Oct 14 13:01 typing_inspect-0.9.0-py3-none-any.whl
-rw-r--r-- 1 root root   347996 Oct 14 13:01 tzdata-2026.5-py2.py3-none-any.whl

第三步，在目标机新建独立虚拟环境并离线安装：

python3 -m venv /opt/venv-hamilton-offline
/opt/venv-hamilton-offline/bin/python -V
/opt/venv-hamilton-offline/bin/pip --version

输出：

Python 3.10.12
pip 22.0.2 from /opt/venv-hamilton-offline/lib/python3.10/site-packages/pip (python 3.10)

/opt/venv-hamilton-offline/bin/pip install --no-index --find-links=/tmp/hamilton-wheels apache-hamilton

输出（完整）：

Looking in links: /tmp/hamilton-wheels
Processing /tmp/hamilton-wheels/apache_hamilton-1.90.0-py3-none-any.whl
Processing /tmp/hamilton-wheels/typing_inspect-0.9.0-py3-none-any.whl
Processing /tmp/hamilton-wheels/typing_extensions-4.16.0-py3-none-any.whl
Processing /tmp/hamilton-wheels/numpy-2.2.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Processing /tmp/hamilton-wheels/pandas-2.3.3-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Processing /tmp/hamilton-wheels/python_dateutil-2.9.0.post0-py2.py3-none-any.whl
Processing /tmp/hamilton-wheels/pytz-2026.5-py2.py3-none-any.whl
Processing /tmp/hamilton-wheels/tzdata-2026.5-py2.py3-none-any.whl
Processing /tmp/hamilton-wheels/mypy_extensions-1.1.0-py3-none-any.whl
Processing /tmp/hamilton-wheels/six-1.17.0-py2.py3-none-any.whl
Installing collected packages: pytz, tzdata, typing_extensions, six, numpy, mypy-extensions, typing_inspect, python-dateutil, pandas, apache-hamilton
Successfully installed apache-hamilton-1.90.0 mypy-extensions-1.1.0 numpy-2.2.6 pandas-2.3.3 python-dateutil-2.9.0.post0 pytz-2026.5 six-1.17.0 typing_extensions-4.16.0 typing_inspect-0.9.0 tzdata-2026.5

第四步，验证。--no-index 参数保证了整个安装过程完全不访问 PyPI，只从本地目录取包：

/opt/venv-hamilton-offline/bin/pip show apache-hamilton

输出（完整）：

Name: apache-hamilton
Version: 1.90.0
Summary: Apache Hamilton (incubating) is a lightweight Python library for directed acyclic graphs (DAGs) of transformations. Your DAG is **portable**; it runs anywhere Python runs, whether it's a script, notebook, Airflow pipeline, FastAPI server, etc. Your DAG is **expressive**; Apache Hamilton has extensive features to define and modify the execution of a DAG (e.g., data validation, experiment tracking, remote execution).
Home-page:
Author:
Author-email: Stefan Krawczyk <stefank@cs.stanford.edu>, Elijah ben Izzy <elijah@dagworks.io>
License:
Location: /opt/venv-hamilton-offline/lib/python3.10/site-packages
Requires: numpy, pandas, typing_extensions, typing_inspect
Required-by:

/opt/venv-hamilton-offline/bin/python -c "from importlib.metadata import version; print(version('apache-hamilton'))"

输出：

1.90.0

功能级验证：把一个数据流示例脚本放入目标机后用离线环境执行，实测运行结果与在线安装环境逐字一致（示例脚本与运行回显见《Apache Hamilton 数据管道实战详解》）。

💡 说明：对比第四节主环境的 pip show 回显，离线环境这份输出里 Home-page 为空、许可证字段显示为 License 而非 License-Expression——这不是包的差异，而是离线 venv 自带 pip 22.0.2 与升级后 pip 26.2.1 的展示字段差异，详见 9.5 节。

六、extras 按需安装

核心包之外，PyPI 元数据实测共提供 23 个 extras（可选依赖组），按「用到才装」的原则引入。清单实录如下：

cli  dask  dask-array  dask-dataframe  dask-diagnostics  dask-distributed  datadog
diskcache  experiments  lsp  mcp  openlineage  pandera  pydantic  pyspark
ray  rich  sdk  slack  tqdm  ui  vaex  visualization

💡 说明：extras 清单里没有独立的 polars 组——polars 支持靠扩展自动加载机制实现（环境中装了 polars 即可用），与旧 sf-hamilton 文档写的清单不同。

以最常用的 [visualization]（DAG 可视化）为例实测安装。它分两层：Python 侧的 graphviz 库与 networkx 由 extras 安装；系统级的 graphviz 二进制需用 apt 另行安装（PyPI 描述原文亦注明 Graphviz 需要在系统上单独安装）。

先装系统级 graphviz：

apt-get install -y graphviz && dot -V

输出（实测节选，末行为 dot -V 回显）：

dot - graphviz version 2.43.0 (0)

安装输出较长：末段出现 Setting up graphviz (2.42.2-6ubuntu0.1) 安装行后完成，apt 包版本为 2.42.2-6ubuntu0.1，而 dot -V 自报运行版本 2.43.0，两者口径不同属正常现象，以 dot -V 为准。

再装 Python 侧 extras：

/opt/venv-hamilton/bin/pip install 'apache-hamilton[visualization]'

输出（完整）：

Installing collected packages: networkx, graphviz

Successfully installed graphviz-0.21 networkx-3.4.2

从回显可知 [visualization] 只追加安装 graphviz 0.21 与 networkx 3.4.2 两个 Python 包，不影响已装的 hamilton 本体与依赖。其余 extras 的安装写法相同，把方括号里的组名替换即可（多个组用逗号连接，如 apache-hamilton[visualization,rich]）。DAG 图的生成全流程实测见《Apache Hamilton 可视化与插件体系详解》。

七、方案对比与选择建议

维度方案 A：在线 pip 安装方案 B：离线 wheel 安装
适用环境能访问 PyPI 的服务器内网或无外网服务器
依赖处理pip 自动解析并下载pip download 预先收集，--no-index --find-links 本地安装
版本一致性安装时取 PyPI 当前版本下载时即固化，介质内版本恒定
实测表现配置代理后整包约 20 秒完成下载一次后，离线安装本地取包即时完成
前置工作量低需要一台联网机 + 介质拷贝

对上表的解读：两条方案安装结果完全一致（同一份 1.90.0 wheel、同一组依赖版本，实测两套虚拟环境的安装清单与运行结果均一致）。区别只在网络路径：日常开发与能出网的服务器直接用方案 A；生产内网、批量交付场景用方案 B，把 /tmp/hamilton-wheels 目录随发布介质分发即可。无论哪条方案，都坚持「一个项目一套虚拟环境」的隔离原则，避免与系统 Python 或其他项目互相污染。

八、配置说明

Apache Hamilton 装完即用，没有常驻服务与配置文件，日常「配置」集中在三件事：虚拟环境的使用方式、网络代理、版本升降级管理。

8.1 虚拟环境使用

两种等价用法：激活后使用，或不激活直接用绝对路径调用。激活属于 Python venv 标准用法——执行 source /opt/venv-hamilton/bin/activate 后当前会话的 python 与 pip 即指向该虚拟环境，deactivate 退出。本文全部示例统一采用绝对路径方式（如 /opt/venv-hamilton/bin/python），好处是不依赖会话激活状态，脚本、计划任务里可直接照抄执行。虚拟环境目录本身即全部内容，备份或迁移就是拷贝目录。

8.2 代理配置

访问 PyPI 缓慢或失败时，在会话内导出代理环境变量后再执行 pip 命令：

export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897

实测背景：直连 PyPI 下载 numpy 时速度仅约 32.5 kB/s，16.8 MB 长时间未完成；导出代理后整包安装约 20 秒完成。需要长期生效时，把以下两行写入 /etc/environment（该文件为系统级环境变量定义，键值对格式，重启后对所有会话生效）：

http_proxy=http://192.168.1.62:7897
https_proxy=http://192.168.1.62:7897

对无法出网的环境则不走代理，直接改用第五节的离线 wheel 方案。

8.3 升级、降级与多版本管理

多版本管理采用「一个版本一套虚拟环境」：本文实测的两套环境 /opt/venv-hamilton 与 /opt/venv-hamilton-offline 并存互不干扰，就是该模式的直接示范。需要新版本时新建一套 venv 安装，验证无误后再切换业务入口，旧环境保留可随时回退。

升级到最新版（已装 1.90.0 时 pip 判定已满足）：

/opt/venv-hamilton/bin/pip install --upgrade apache-hamilton

输出（关键行）：

Requirement already satisfied: apache-hamilton in /opt/venv-hamilton/lib/python3.10/site-packages (1.90.0)

降级则有一个必须绕开的坑：直接指定 apache-hamilton==1.89.0 会失败。实测完整报错如下：

/opt/venv-hamilton-offline/bin/pip install apache-hamilton==1.89.0

输出（完整，实测失败）：

Collecting apache-hamilton==1.89.0
  Downloading apache-hamilton-1.89.0.tar.gz (368 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 368.8/368.8 KB 23.8 MB/s eta 0:00:00
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
  Getting requirements to build wheel: started
  Getting requirements to build wheel: finished with status 'done'
  Preparing metadata (pyproject.toml): started
  Preparing metadata (pyproject.toml): finished with status 'done'
  WARNING: Generating metadata for package apache-hamilton produced metadata for project name sf-hamilton. Fix your #egg=apache-hamilton fragments.
Discarding https://files.pythonhosted.org/packages/ed/68/9aa7256e2530fab8c9918c3698aff7f32b2d0b7f0d00c6fea68728f23348/apache-hamilton-1.89.0.tar.gz#sha256=b785dc396e462c93125a1663420f11d85ae8ee7ea1461ccdf6eaf0b2a964a68c (from https://pypi.org/simple/apache-hamilton/) (requires-python:<4,>=3.8.1): Requested sf-hamilton from https://files.pythonhosted.org/packages/ed/68/9aa7256e2530fab8c9918c3698aff7f32b2d0b7f0d00c6fea68728f23348/apache-hamilton-1.89.0.tar.gz#sha256=b785dc396e462c93125a1663420f11d85ae8ee7ea1461ccdf6eaf0b2a964a68c has inconsistent name: filename has 'apache-hamilton', but metadata has 'sf-hamilton'
ERROR: Could not find a version that satisfies the requirement apache-hamilton==1.89.0 (from versions: 1.89.0, 1.90.0.dev0, 1.90.0)
ERROR: No matching distribution found for apache-hamilton==1.89.0

报错核心是倒数第二行的 inconsistent name：1.89.0 的源码包文件名是 apache-hamilton，内部元数据却写着 sf-hamilton，pip 拒绝安装。正确降级方式是走旧包名：

/opt/venv-hamilton-offline/bin/pip install sf-hamilton==1.89.0

输出（实测节选，保留关键行）：

Collecting sf-hamilton==1.89.0
  Downloading sf_hamilton-1.89.0-py3-none-any.whl (468 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 468.9/468.9 KB 36.7 MB/s eta 0:00:00
Requirement already satisfied: pandas in /opt/venv-hamilton-offline/lib/python3.10/site-packages (from sf-hamilton==1.89.0) (2.3.3)
Requirement already satisfied: numpy in /opt/venv-hamilton-offline/lib/python3.10/site-packages (from sf-hamilton==1.89.0) (2.2.6)
Installing collected packages: sf-hamilton
Successfully installed sf-hamilton-1.89.0

⚠️ 双包名混装陷阱：这一步装完，同一个虚拟环境里就同时存在 apache-hamilton 1.90.0 与 sf-hamilton 1.89.0 两个发行版，它们安装到同一个 hamilton 包目录，实际 import 到的是后装的 1.89.0 的文件。验证如下：

/opt/venv-hamilton-offline/bin/python -c "import hamilton; print(hamilton.__version__)"
/opt/venv-hamilton-offline/bin/pip list | grep -i hamilton

输出：

(1, 89, 0)
apache-hamilton   1.90.0
sf-hamilton       1.89.0

此时再执行 pip install --upgrade apache-hamilton 会发现 pip 报 already satisfied (1.90.0)，但 import 版本仍是 1.89.0——升级对混装无效：

/opt/venv-hamilton-offline/bin/pip install --upgrade apache-hamilton

输出（关键行）：

Requirement already satisfied: apache-hamilton in /opt/venv-hamilton-offline/lib/python3.10/site-packages (1.90.0)

/opt/venv-hamilton-offline/bin/python -c "import hamilton; print(hamilton.__version__)"

输出：

(1, 89, 0)

恢复干净状态的标准动作是：卸载旧名发行版，再强制重装新名发行版：

/opt/venv-hamilton-offline/bin/pip uninstall -y sf-hamilton
/opt/venv-hamilton-offline/bin/pip install --force-reinstall --no-deps apache-hamilton==1.90.0

输出（完整）：

Found existing installation: sf-hamilton 1.89.0
Uninstalling sf-hamilton-1.89.0:
  Successfully uninstalled sf-hamilton-1.89.0
Collecting apache-hamilton==1.90.0
  Downloading apache_hamilton-1.90.0-py3-none-any.whl (475 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 475.2/475.2 KB 27.4 MB/s eta 0:00:00
Installing collected packages: apache-hamilton
  Attempting uninstall: apache-hamilton
    Found existing installation: apache-hamilton 1.90.0
    Uninstalling apache-hamilton-1.90.0:
      Successfully uninstalled apache-hamilton-1.90.0
Successfully installed apache-hamilton-1.90.0

验证恢复结果：

/opt/venv-hamilton-offline/bin/python -c "import hamilton; print(hamilton.__version__)"
/opt/venv-hamilton-offline/bin/pip list | grep -i hamilton

输出：

(1, 90, 0)
apache-hamilton   1.90.0

对以上过程的解读：新旧两个 PyPI 包名在文件系统层面共用同一个 hamilton 目录，pip 按发行版（dist-info）管理元数据，因此两个发行版可以同时出现在 pip list 里，而 import 只认实际文件。经验法则：同一虚拟环境内新旧包名只允许存在一个；升级降级前先 pip list | grep -i hamilton 确认当前只有单一名，出现双名就按上面的卸载加重装流程恢复。

九、常见问题（排障实录）

以下问题均在实测中真实出现过，按「现象、原因、解决」整理，可直接对照处置。

9.1 导入 pandas 插件报 ModuleNotFoundError: No module named 'packaging'

现象：手动加载 pandas 后端扩展（如 from hamilton.plugins import pandas_extensions）时抛出以下回显：

File "/opt/venv-hamilton/lib/python3.10/site-packages/hamilton/plugins/pandas_extensions.py", line 27, in <module>
    from packaging.version import Version
ModuleNotFoundError: No module named 'packaging'

原因：1.90.0 实测存在上游打包问题——pandas_extensions 模块需要 packaging，但 apache-hamilton 的依赖声明（Requires 仅有 numpy、pandas、typing_extensions、typing_inspect）与 pandas 自身的依赖都没有包含它。

解决：

/opt/venv-hamilton/bin/pip install packaging

输出（实测节选）：

Downloading packaging-26.3-py3-none-any.whl (129 kB)
Installing collected packages: packaging
Successfully installed packaging-26.3

影响面实测结论：不装 packaging 且保持默认扩展自动加载时，基础数据流仍能跑（自动加载器会静默跳过加载失败的插件），但所有依赖 DataFrame 类型注册的功能都会失败；装上 packaging 后一切正常。凡是用到 DataFrame 类型感知的功能，都应先执行这条兜底安装。

9.2 关闭扩展自动加载后报 Registered types are {}

现象：调用 registry.disable_autoload() 之后，使用 DataFrame 相关装饰器（如 @extract_columns）在导入阶段即报错：

NotImplementedError: Cannot get column type for [<class 'pandas.core.frame.DataFrame'>]. Registered types are {}

随后还有一条：

hamilton.function_modifiers.base.InvalidDecoratorException: Error <function raw_df at 0x74e7a3cd2ef0> does not output a type we know about. Is it a dataframe type we support?

原因：disable_autoload() 关闭了扩展自动加载，pandas 的 DataFrame 类型没有注册进类型注册表。解决：在 disable_autoload 之后手动加载 pandas 后端扩展，from hamilton.plugins import pandas_extensions；同时按 9.1 节先装好 packaging。

9.3 PyPI 下载缓慢或超时

现象：pip install apache-hamilton 长时间停留在下载阶段，实测直连速度约 32.5 kB/s。解决：按 8.2 节导出代理后重试，实测约 20 秒完成；完全无法出网的环境改走第五节离线方案。

9.4 安装 apache-hamilton==1.89.0 报包名不一致

现象：pip 报 inconsistent name 并拒绝安装（完整报错见 8.3 节），错误行摘录：

ERROR: Could not find a version that satisfies the requirement apache-hamilton==1.89.0 (from versions: 1.89.0, 1.90.0.dev0, 1.90.0)
ERROR: No matching distribution found for apache-hamilton==1.89.0

原因：apache-hamilton 名下的 1.89.0 只发布了 sdist，内部元数据仍是旧名 sf-hamilton。解决：改用旧包名安装 pip install sf-hamilton==1.89.0，实测成功（回显见 8.3 节）。

9.5 pip show 字段缺失（Home-page 为空、许可证字段名不同）

现象：第五节离线环境的 pip show apache-hamilton 输出中 Home-page 为空、许可证字段显示为 License；而第四节主环境显示 Home-page 网址与 License-Expression: Apache-2.0。原因：离线 venv 自带 pip 22.0.2，主环境已升级到 pip 26.2.1，两个 pip 版本对 show 字段的解析与展示能力不同，与包本身无关。解决：在对应虚拟环境内执行 pip install --upgrade pip 升级后即显示完整字段。

十、卸载与清理

卸载分两个层次：只卸 Hamilton 本体，或连同虚拟环境整体回收。

只卸本体（依赖保留）：

/opt/venv-hamilton-offline/bin/pip uninstall -y apache-hamilton

输出（完整）：

Found existing installation: apache-hamilton 1.90.0
Uninstalling apache-hamilton-1.90.0:
  Successfully uninstalled apache-hamilton-1.90.0

验证卸载结果与依赖去留：

/opt/venv-hamilton-offline/bin/pip show apache-hamilton
/opt/venv-hamilton-offline/bin/pip list | grep -Ei 'numpy|pandas|typing'

输出（完整）：

WARNING: Package(s) not found: apache-hamilton
numpy             2.2.6
pandas            2.3.3
typing_extensions 4.16.0
typing-inspect    0.9.0

实测结论：pip uninstall apache-hamilton 只卸载 hamilton 本体，numpy、pandas 等依赖原样保留在环境中——这些依赖可能被同环境的其他项目使用，pip 不会级联删除。若要整体回收（依赖一并清掉），直接删除虚拟环境目录即可：

rm -rf /opt/venv-hamilton /opt/venv-hamilton-offline

该命令无回显，执行后目录即被整体移除；离线 wheel 目录不再需要时同样删除：

rm -rf /tmp/hamilton-wheels

清理判断建议：环境确属专用则 rm -rf 整体回收最干净；环境与其他项目共用则只卸本体，依赖留给共用方。

十一、参考链接