Pathway 安装指南：pip 一键安装、可选依赖组、Docker 与 License Key 配置

本文以 Pathway 官方用户指南中的 Installation 文档为核心，完整覆盖从 pip 快速安装、可选依赖组（extras）选择、Docker 镜像使用，到 License Key 配置与企业版私有 PyPI 仓库安装的全流程。读完本文，你可以独立完成 Pathway Live Data Framework 的环境搭建，理解每个可选依赖组背后的实际包清单，并能从源码层面确认 License Key 的读取、校验与报错机制。

快速安装：一条命令装好 Python 包与 Rust 引擎

Pathway 的官方安装入口非常简单，通过 pip 即可安装最新版：

pip install -U pathway

这条命令会安装运行 Pathway 流水线所需的全部基础依赖，其中包括用 Rust 编写的核心执行引擎。从 pyproject.toml 可以看到，该包并非纯 Python 项目：构建系统使用 maturin，并在 [tool.maturin] 段中声明 module-name = "pathway.engine"、features = ["pyo3/extension-module"]，说明 Rust 引擎通过 PyO3 以 pathway.engine 扩展模块的形式编译进 wheel。也就是说，pip install pathway 安装到的其实是一个"Python API + Rust 引擎"的混合发行包。

官方文档明确给出的平台支持范围是：

Pathway Live Data Framework 支持 MacOS 和 Linux，目前不支持 Windows。Windows 用户可以考虑使用 Windows Subsystem for Linux (WSL)、Docker 或虚拟机。

此外，若要快速起步一个 Pathway 项目，官方还提供了一个 cookiecutter 项目模板（cookiecutter-pathway）用于生成标准项目骨架，本文不展开外链，可直接在仓库的 examples 目录下查看可运行的示例项目作为替代起点。

安装内容解析：Python 版本要求与基础依赖

pip install pathway 装进来的是什么？以当前仓库的 pyproject.toml 为准：

• Python 版本要求：requires-python = ">=3.10"，即必须使用 Python 3.10 及以上版本（企业版安装章节中同样强调"使用 python3.10 或更高"）。
• 声明的项目描述："Pathway Live Data Framework is a data processing framework which takes care of streaming data updates for you."

基础依赖（dependencies 段）摘录如下，这些包会随主包一起安装：

依赖	版本约束	用途定位
numpy	>= 1.21	数值/表格计算基础
pandas	>= 2.1	DataFrame 数据操作
pyarrow	>= 10.0.0, < 26.0.0	Arrow 列式数据格式
pydantic	~= 2.9	数据校验
scikit-learn	>= 1.0	机器学习工具
shapely / geopy / h3	>= 2.0.1 / >= 2.4.0 / >= 4	地理空间数据处理
boto3	>= 1.26.76, < 2.0.0	对象存储（S3 等）访问
deltalake	>= 1.6.0, < 2.0.0	Delta Lake 读写
sqlalchemy / sqlmodel	>= 2.0.43 / >= 0.0.24	数据库连接
fastapi / uvicorn	>= 0.116.1 / >= 0.29.0	Web 服务运行时
opentelemetry-api/sdk、opentelemetry-exporter-otlp-proto-grpc	>= 1.22.0	可观测性/监控
panel / jupyter_bokeh	>= 1.3.1 / >= 3.0.7	交互式可视化
diskcache、aiohttp、requests 等	—	缓存与网络基础

可以看到，基础安装已经覆盖了表格计算、流式数据 I/O（S3、Delta Lake）、数据库、Web 服务与监控等能力，但默认不包含任何 LLM 相关库——这一点与官方文档"不安装任何外部 LLM 库"的描述一致。

安装完成后，官方文档建议用官方示例做首次体验，本仓库内对应的入口是 first-realtime-app 文档，其中给出了几分钟内跑通第一个实时应用（notebook 或 docker 两种形态）的步骤。

可选依赖组（Extras）：按需安装，精确控制体积

官方文档把依赖拆分成了若干组，让用户自行控制安装内容。pip install pathway 只安装 Rust 引擎和运行框架所必需的内容；若要跑 AI 流水线，则安装 pathway[xpack-llm]。多个组可以一次安装，例如 pip install "pathway[xpack-llm, airbyte]"。

文档中的官方分组速查表

Package	Installation Command	Description	Notes
Basic LLM Tooling	pip install "pathway[xpack-llm]"	安装常用 LLM 库（OpenAI、Langchain、LlamaIndex）	可进一步参考 LLM xPack 概述 与各 LLM 示例
Local LLM Deployment	pip install "pathway[xpack-llm-local]"	本地部署推理所需库	—
Parsing Documents	pip install "pathway[xpack-llm-docs]"	文档解析工具（PDF、Microsoft Word）	—
Airbyte Connector	pip install "pathway[airbyte]"	Airbyte 支持	参考 Airbyte ETL 示例
SharePoint Connector	pip install "pathway[xpack-sharepoint]"	SharePoint 支持	需要（免费的）license key
All	pip install "pathway[all]"	安装全部可选包	—

结合 pyproject.toml 看每个组实际装了什么

文档指向 pyproject.toml 查看各组内容，当前仓库中的 [project.optional-dependencies] 给出了完整清单，比文档表格更细：

• xpack-llm（基础 LLM 工具链）：openai、litellm（带按 Python 版本区分的精细约束）、cohere、tiktoken、aiobotocore、langchain/langchain_community（>= 0.2.0, < 0.4.0）、llama-index-core 及 Pathway 专用的 llama-index-readers-pathway、llama-index-retrievers-pathway、instructor、google-generativeai，以及对 protobuf、grpcio-status 等一系列 Google 生态包的显式版本上限——注释里解释了这些上限是为了让 pip 求解器不必回溯几十个版本。
• xpack-llm-local：sentence_transformers、transformers >= 4.50.2, < 5.0，用于本地模型推理。
• xpack-llm-docs：docling、docling-core、python-docx、unstructured[all-docs]、pdf2image、pypdf 等，其中 paddleocr 在 Python 3.14 下被条件排除（无 cp314 wheel）。
• xpack-sharepoint：仅 Office365-REST-Python-Client >= 2.5.3。
• airbyte：google-cloud-run、google-cloud-secret-manager、google-cloud-logging、pyyaml、jinja2。
• all：聚合了 pyfilesystem、sql、xpack-llm、xpack-llm-local、xpack-llm-docs、xpack-sharepoint、airbyte、milvus、twelvelabs 全部九个子组。

此外还有几个未在文档表格中列出、但配置文件中真实存在的组，值得按需选用：

• sql：sqlglot == 10.6.1，注释说明新版本与当前 pw.sql 实现不兼容，故被固定版本。
• milvus：pymilvus >= 2.4.2, < 3、milvus-lite >= 2.4.2, < 3，用于 Milvus 向量数据库。
• pyfilesystem：fs >= 2.4.16，用于 PyFilesystem 文件系统抽象。
• twelvelabs：twelvelabs >= 1.2.8。
• tests：pytest 全家桶及 pathway[all]，主要用于开发/集成测试环境（对应 integration_tests 目录下的用例）。

使用 Docker 运行 Pathway

官方同时提供 Docker 方式。官方镜像发布在 Docker Hub 的 pathwaycom/pathway，基本操作为：

docker pull pathwaycom/pathway

更完整的容器化运行方式（构建、运行、Jupyter 集成等）参见仓库内的专门文档 Docker Deployment，以及 Jupyter + Docker 一篇。对于前文提到的 Windows 用户，Docker/WSL 也是官方推荐的替代运行环境之一。

License Key：BSL 1.1 许可与免费授权机制

官方文档对许可的表述是：

• Pathway Live Data Framework 采用 BSL 1.1 许可证分发（见 LICENSE.txt），允许无限的非商业用途以及大多数商业目的的免费使用；
• 主仓库中的代码在 4 年后自动转为开源（Apache 2.0）；
• 与之互补的一些公共仓库（示例、库、连接器等）直接采用 MIT 许可证；
• 部分功能（如监控 monitoring、高级连接器如 SharePoint）需要免费的 license key。

源码佐证：License Key 从哪里读取、如何校验

从 Python 侧看，license key 由配置对象统一承载。config.py 中 PathwayConfig 数据类的字段声明为：

# python/pathway/internals/config.py (L72)
license_key: str | None = _env_field("PATHWAY_LICENSE_KEY")

即启动时默认从环境变量 PATHWAY_LICENSE_KEY 读取；随后可通过公开 API 在代码中设置或清除：

# python/pathway/internals/config.py (L142-L158)
def set_license_key(key: str | None) -> None:
    """Sets Pathway Live Data Framework license key. ...
    Args:
        key: The license key to be set. If None, any existing license key will be cleared.
    """
    get_pathway_config().license_key = key

该函数通过 python/pathway/init.py 重导出，因此可以在代码中直接以 pw.set_license_key(...) 调用。

从 Rust 引擎侧看，license.rs 定义了 License 枚举的三种状态：LicenseKey（普通在线 key）、OfflineLicense（离线许可证文件）、NoLicenseKey。其 new() 构造逻辑（L42-L56）说明了 key 的形态判定：空值视为无 key；以 -----BEGIN LICENSE FILE----- 开头的内容按离线许可证解析；否则当作在线 license key。值得注意的是，非 enterprise 构建下，离线许可证会直接报 OfflineLicenseNotAllowed 错误（L51-L55），离线 key 属于企业构建的能力。

授权不足时的报错信息也由该文件给出（L128-L131），会明确提示"该功能需要免费的 Pathway license key，设置 PATHWAY_LICENSE_KEY 环境变量"，并在 config.py 的 _check_entitlements（L122-L125）中经由 api.check_entitlements 将 Python 侧的许可请求转发到 Rust 侧完成校验。

企业版包安装：私有 PyPI 仓库 + License 配置

前提：使用 python3.10 或更高版本。

步骤一：配置 pip 指向私有 PyPI 仓库

创建或修改 pip 配置文件，将其指向你的私有仓库。向 ~/.pip/pip.conf 添加：

[global]
extra-index-url = https://<username>:<password>@<URL>

然后安装：

pip install -U pathway

也可以不写配置文件，直接把 extra index url 传给安装命令：

pip install -U pathway --extra-index-url=https://<username>:<password>@<URL>

其中 <URL>、<username>、<password> 需替换为从 Pathway 获得的凭证。

步骤二：配置企业 License

从 Pathway 获取 license 文件后，用以下任一方式设置：

方式 1：环境变量（指向文件）：

PATHWAY_LICENSE_KEY=file:///path/to/license.lic

或内联直接写入 key 内容：

PATHWAY_LICENSE_KEY="-----BEGIN LICENSE FILE-----
...
-----END LICENSE FILE-----"

方式 2：在 Python 代码中设置：

import pathway as pw

pw.set_license_key("file:///path/to/license.lic")

# 或者内联
pw.set_license_key("""-----BEGIN LICENSE FILE-----
...
-----END LICENSE FILE-----""")

pw.run()

从 license.rs 的 read_license_to_string 实现可以印证上述两种形态的底层处理：key 若带 file:// 前缀，则剥离前缀后按本地文件路径读取文件内容；否则原样作为 key 字符串使用。这与 Python 侧 set_license_key / PATHWAY_LICENSE_KEY 的取值完全对应。结合前文 License::new() 的逻辑（内联许可证需以 -----BEGIN LICENSE FILE----- 开头才被识别为 OfflineLicense），可以推断：离线/文件型 license 是企业构建下的工作方式，普通 PyPI 发行版主要面向在线 license key。

小结与检查清单

• pip install -U pathway：一条命令装好 Python API + Rust 引擎，要求 Python ≥ 3.10，仅支持 MacOS/Linux（Windows 请用 WSL、Docker 或 VM）；
• 依赖按需分组：LLM 流水线装 pathway[xpack-llm]，本地推理加 xpack-llm-local，文档解析加 xpack-llm-docs，全量安装用 pathway[all]；各组的真实包清单以 pyproject.toml 的 [project.optional-dependencies] 段为准；
• Docker 用户：docker pull pathwaycom/pathway，完整用法见 Docker Deployment；
• 免费 license key 通过 PATHWAY_LICENSE_KEY 环境变量或 pw.set_license_key() 设置，监控、SharePoint 等高级功能需要它；企业场景则通过 ~/.pip/pip.conf 配置私有索引并支持 file:// 离线许可证；
• 首次跑通建议直接参考 第一个实时应用 文档，安装完成后几分钟内即可验证环境是否就绪。