Ubuntu 22.04 安装 Apache GraphAr 指南

Ubuntu 22.04 从零安装 Apache GraphAr Python SDK 完整指南：版本选型与 pygraphar 包名陷阱排障、在线 pip 与离线 wheel 两种安装方案实测、GAR_TEST_DATA 配置、升降级与卸载清理。

Apache GraphArApacheApache GraphAr大数据安装部署Ubuntu 22.042026/10/14

Ubuntu 22.04 安装 Apache GraphAr 指南

目标：在全新 Ubuntu 22.04 服务器上从零安装 Apache GraphAr 官方 Python SDK（PyPI 包名 graphar），覆盖版本选型、包名陷阱排障、在线与离线两种安装方案、基础配置、版本升降级与卸载清理。所有命令与回显均在真实环境完整执行并记录（Ubuntu 22.04.5 LTS，Python 3.10.12，graphar 0.13.0.dev1）。

一、环境信息

本指南的实测环境如下，读者在同等环境操作时回效应可完全对齐：

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64），root 用户
  • Python：3.10.12（系统自带）
  • 目标组件：Apache GraphAr Python SDK 0.13.0.dev1（PyPI 包 graphar，含 C++ 核心库、Python 绑定与 CLI 工具）
  • 安装方式：pip（在线方案 A 与离线 wheel 方案 B）
  • 虚拟环境路径：/opt/venv-graphar（方案 A）、/opt/venv-graphar-offline（方案 B 演示）

实测环境的基础版本确认：

python3 -V && pip3 --version

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

💡 说明：Ubuntu 22.04 自带 Python 3.10，满足 graphar wheel 的最低要求（cp39 起）；系统自带 pip 22.0.2 较旧，本指南会在虚拟环境中先升级 pip 再安装，避免老版本 pip 的兼容性问题。

二、前置条件

2.1 系统与网络要求

  • 能访问 Ubuntu 软件源（安装 Python 基础包）；
  • 能访问 PyPI 官方源 pypi.org（在线方案 A 必需；方案 B 的下载机需要，目标机器不需要）；
  • 磁盘空间 200MB 以上（wheel 及依赖约 30MB，虚拟环境约 120MB）。

2.2 安装基础软件包

全新系统先安装 Python 与虚拟环境支持（实测回显末尾节选）：

apt-get update && apt-get install -y python3 python3-venv python3-pip curl

Setting up python3-pip (22.0.2+dfsg-1ubuntu0.7) ...
Setting up python3-dev (3.10.6-1~22.04.1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

安装完成后的验证手段：

python3 -V && python3 -m venv --help | head -2

Python 3.10.12
usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]

2.3 创建并升级虚拟环境

不要把 GraphAr 装进系统 Python，统一使用虚拟环境隔离依赖：

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

  Downloading pip-26.2.1-py3-none-any.whl (1.8 MB)
    Found existing installation: pip 22.0.2
    Uninstalling pip-22.0.2:
      Successfully uninstalled pip-22.0.2
Successfully installed pip-26.2.1

💡 说明：升级 pip 非常关键——实测在 pip 26.2.1 下 pip install graphar 无需额外参数即可正确回退安装预发布版本（见 4.2 节回显），老版本 pip 遇到仅有预发布的包可能直接报错。

三、版本选型说明

3.1 包名辨析：graphar 是唯一正确包名（排障实录）

PyPI 上存在两个名字极像的包，实测确认只有 graphar 是 Apache GraphAr 官方包：

pip index versions pygraphar

pygraphar (0.0.1)
Available versions: 0.0.1

pip index versions graphar --pre

graphar (0.13.0.dev1)
Available versions: 0.13.0.dev1, 0.13.0.dev0
  INSTALLED: 0.13.0.dev1
  LATEST:    0.13.0.dev1

用 PyPI JSON 接口核实 pygraphar 的真实身份（实测）：

curl -s https://pypi.org/pypi/pygraphar/json | python3 -c "import json,sys; d=json.load(sys.stdin); i=d['info']; print('name:', i['name']); print('version:', i['version']); print('summary:', i['summary']); print('home:', i['home_page']); print('releases:', sorted(d['releases'].keys()))"

name: pygraphar
version: 0.0.1
summary: None
home: https://github.com/alibaba/GraphScope
releases: ['0.0.1']

可见 pygraphar 归属 GraphScope 项目，只是占位包。误装它的实测结果：

pip install pygraphar

Collecting pygraphar
  Downloading pygraphar-0.0.1-py3-none-any.whl (10 kB)
Collecting etcd-distro>=3.5.1 (from pygraphar)
  Downloading etcd_distro-1.3.3-py3-none-any.whl.metadata (3.6 kB)
INFO: pip is looking at multiple versions of pygraphar to determine which version is compatible with other requirements. This could take a while.
（中间为依赖解析与版本列举行）
ERROR: No matching distribution found for graphscope-client==0.0.1

⚠️ 注意：pygraphar 会尝试拉取早已不存在的 graphscope-client 0.0.1 并安装失败；即便未来装上，导入的也是 GraphScope 的模块而非 GraphAr。请记住结论——安装 Apache GraphAr 用 pip install graphar。

3.2 版本形态与可用版本

graphar 当前只有预发布版本（0.13.0.dev0、0.13.0.dev1），无正式稳定版：

  • 推荐 0.13.0.dev1：本指南全部实测基于该版本，graphar --version 返回 GraphAr CLI Version: 0.13.0.dev1；
  • 0.13.0.dev0 实测不可用：安装后 import graphar 报动态链接符号错误（复现回显见 7.3 节），属该 dev 版本自身的打包缺陷；
  • 版本查询注意：pip index versions graphar 不带 --pre 会报 ERROR: No matching distribution found for graphar（实测，详见 8.1 节），因为查询行为默认排除预发布版本。

3.3 Python 版本与 wheel 兼容范围

维度实测结论
wheel 覆盖cp39、cp310、cp311、cp312、cp313（manylinux x86_64），requires-python >= 3.9
本指南环境cp310（Python 3.10.12），wheel 约 22MB
运行时依赖typer、pydantic、pyyaml、pytest 四个纯 Python/C 扩展包，无需编译工具链
源码构建仅当需要从源码构建时才要求 Python >= 3.10 并安装 pyarrow==24.0.0 等构建依赖
Java/Spark 侧Maven Central 无 org.apache.graphar 构件（实测访问 https://repo1.maven.org/maven2/org/apache/graphar/ 返回 404），只能源码构建，不在本指南范围

💡 说明：日常使用装 wheel 即可，没有编译环节；python3-dev 在 2.2 节随系统包一并装上，仅为源码构建场景预留。

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

4.1 方案说明

目标机器能访问 PyPI 时，一条命令完成安装，pip 自动解析并安装 19 个依赖包。这是官方推荐、也是实测最可靠的路径。

4.2 安装步骤与实测回显

/opt/venv-graphar/bin/pip install graphar

Collecting graphar
  Downloading graphar-0.13.0.dev1-cp310-cp310-manylinux_2_28_x86_64.whl (15.3 MB)
Installing collected packages: typing-extensions, tomli, shellingham, pyyaml, pygments, pluggy, packaging, mdurl, iniconfig, annotated-types, annotated-doc, typing-inspection, pydantic-core, markdown-it-py, exceptiongroup, rich, pytest, pydantic, typer, graphar
Successfully installed annotated-doc-0.0.5 annotated-types-0.8.0 exceptiongroup-1.3.1 graphar-0.13.0.dev1 iniconfig-2.3.1 markdown-it-py-4.2.0 mdurl-0.1.2 packaging-26.3 pluggy-1.6.0 pydantic-2.11.10 pydantic-core-2.33.2 pygments-2.21.0 pytest-7.4.4 pyyaml-6.0.3 rich-15.0.0 shellingham-1.5.4 tomli-2.5.0 typer-0.27.3 typing-extensions-4.16.0 typing-inspection-0.4.4

⚠️ 注意：不带 --pre 也能装上——因为包没有稳定版本，pip 会回退选择最新预发布版本 0.13.0.dev1（实测回显即证）。若需显式锁定，可写 pip install graphar==0.13.0.dev1。

4.3 安装验证

三重验证：包信息、模块导入、CLI 可用性（实测回显）：

/opt/venv-graphar/bin/pip show graphar

Name: graphar
Version: 0.13.0.dev1
Summary: An open source, standard data file format for graph data storage and retrieval.
Author-email: GraphAr community <dev@graphar.apache.org>
License: Apache-2.0
Location: /opt/venv-graphar/lib/python3.10/site-packages
Requires: pydantic, pytest, pyyaml, typer
Required-by:

/opt/venv-graphar/bin/python -c "import graphar; import importlib.metadata as im; print('graphar version:', im.version('graphar'))"

graphar version: 0.13.0.dev1

/opt/venv-graphar/bin/graphar --version

GraphAr CLI Version: 0.13.0.dev1

三项全部通过即安装成功。

五、方案 B：离线 wheel 包安装（内网环境）

5.1 方案说明

目标机器无法访问公网时，先用一台联网机器把 graphar 及全部依赖的 wheel 收集到目录，再拷贝到目标机器离线安装。实测两步均在同一台服务器上完成（以 /tmp/graphar-wheels 模拟离线包仓库）。

5.2 第一步：联网环境收集 wheel

/opt/venv-graphar/bin/pip download graphar --pre -d /tmp/graphar-wheels

Collecting graphar
  Using cached graphar-0.13.0.dev1-cp310-cp310-manylinux_2_28_x86_64.whl.metadata (3.7 kB)
Collecting typer~=0.1 (from graphar)
  Using cached typer-0.27.3-py3-none-any.whl.metadata (16 kB)
（中间为 pydantic、pytest、pyyaml 及传递依赖的解析行）
Saved ./tmp/graphar-wheels/graphar-0.13.0.dev1-cp310-cp310-manylinux_2_28_x86_64.whl
（中间为其余 19 个依赖 wheel 的 Saved 行）
Successfully downloaded graphar pydantic pydantic-core pytest pluggy pyyaml typer annotated-doc annotated-types exceptiongroup rich pygments markdown-it-py mdurl shellingham tomli typing-extensions typing-inspection iniconfig packaging

收集结果核对（20 个 wheel、合计 27MB，实测清单）：

find /tmp/graphar-wheels -type f | sort && du -sh /tmp/graphar-wheels

/tmp/graphar-wheels/annotated_doc-0.0.5-py3-none-any.whl
/tmp/graphar-wheels/annotated_types-0.8.0-py3-none-any.whl
/tmp/graphar-wheels/exceptiongroup-1.3.1-py3-none-any.whl
/tmp/graphar-wheels/graphar-0.13.0.dev1-cp310-cp310-manylinux_2_28_x86_64.whl
/tmp/graphar-wheels/iniconfig-2.3.1-py3-none-any.whl
/tmp/graphar-wheels/markdown_it_py-4.2.0-py3-none-any.whl
/tmp/graphar-wheels/mdurl-0.1.2-py3-none-any.whl
/tmp/graphar-wheels/packaging-26.3-py3-none-any.whl
/tmp/graphar-wheels/pluggy-1.6.0-py3-none-any.whl
/tmp/graphar-wheels/pydantic-2.11.10-py3-none-any.whl
/tmp/graphar-wheels/pydantic_core-2.33.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
/tmp/graphar-wheels/pygments-2.21.0-py3-none-any.whl
/tmp/graphar-wheels/pytest-7.4.4-py3-none-any.whl
/tmp/graphar-wheels/pyyaml-6.0.3-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
/tmp/graphar-wheels/rich-15.0.0-py3-none-any.whl
/tmp/graphar-wheels/shellingham-1.5.4-py2.py3-none-any.whl
/tmp/graphar-wheels/tomli-2.5.0-py3-none-any.whl
/tmp/graphar-wheels/typer-0.27.3-py3-none-any.whl
/tmp/graphar-wheels/typing_extensions-4.16.0-py3-none-any.whl
/tmp/graphar-wheels/typing_inspection-0.4.4-py3-none-any.whl
27M     /tmp/graphar-wheels

⚠️ 注意：wheel 与目标机器的 Python 版本、操作系统平台绑定。本清单是 cp310 + manylinux x86_64 组合；若目标机器 Python 版本不同，下载时用 pip download 的 --python-version、--platform、--only-binary 参数按目标环境重新收集。

5.3 第二步：目标机器离线安装

目标机器只需有 Python 与 venv，全程不访问公网：

python3 -m venv /opt/venv-graphar-offline && /opt/venv-graphar-offline/bin/pip install --no-index --find-links /tmp/graphar-wheels graphar

Looking in links: /tmp/graphar-wheels
Processing /tmp/graphar-wheels/graphar-0.13.0.dev1-cp310-cp310-manylinux_2_28_x86_64.whl
（中间为 19 个依赖 wheel 的 Processing 行）
Installing collected packages: typing-extensions, tomli, shellingham, pyyaml, pygments, pluggy, packaging, mdurl, iniconfig, annotated-types, annotated-doc, typing-inspection, pydantic-core, markdown-it-py, exceptiongroup, rich, pytest, pydantic, typer, graphar
Successfully installed annotated-doc-0.0.5 annotated-types-0.8.0 exceptiongroup-1.3.1 graphar-0.13.0.dev1 iniconfig-2.3.1 markdown-it-py-4.2.0 mdurl-0.1.2 packaging-26.3 pluggy-1.6.0 pydantic-2.11.10 pydantic-core-2.33.2 pygments-2.21.0 pytest-7.4.4 pyyaml-6.0.3 rich-15.0.0 shellingham-1.5.4 tomli-2.5.0 typer-0.27.3 typing-extensions-4.16.0 typing-inspection-0.4.4

5.4 离线安装验证

/opt/venv-graphar-offline/bin/pip show graphar | head -3

Name: graphar
Version: 0.13.0.dev1
Summary: An open source, standard data file format for graph data storage and retrieval.

/opt/venv-graphar-offline/bin/graphar --version

GraphAr CLI Version: 0.13.0.dev1

六、方案对比与选择建议

维度方案 A：在线 pip方案 B：离线 wheel
目标机器联网需要不需要
操作步骤1 条命令下载收集 + 拷贝 + 2 条命令
版本控制pip 自动解析最新预发布wheel 目录里有什么就装什么，完全锁定
适用场景开发机、可联网服务器（推荐）内网机器、批量部署、审计要求
局限依赖 PyPI 可用性wheel 必须与目标 Python 版本/平台匹配

选择建议：默认用方案 A；批量部署到同规格机器时，用方案 B 的 wheel 目录作为统一分发物；两方案实测安装结果完全一致（同为 0.13.0.dev1 + 19 个同版本依赖）。

七、配置说明

7.1 虚拟环境激活与命令路径

两种日常用法：激活后直接用短命令，或不激活用绝对路径（实测等价）。激活后的命令定位与版本确认（实测回显）：

source /opt/venv-graphar/bin/activate && which graphar && graphar --version

/opt/venv-graphar/bin/graphar
GraphAr CLI Version: 0.13.0.dev1

不激活时用 /opt/venv-graphar/bin/graphar、/opt/venv-graphar/bin/python 绝对路径调用（本指南全部回显均基于绝对路径方式，脚本化部署推荐该方式）。

7.2 测试数据环境变量 GAR_TEST_DATA

官方示例与测试脚本通过 GAR_TEST_DATA 定位测试数据根目录。先克隆源码仓库，并把测试数据仓库克隆到源码仓库的 testing 子目录（与官方示例的相对布局一致）：

git clone --depth 1 https://github.com/apache/incubator-graphar.git /opt/incubator-graphar
git clone --depth 1 https://github.com/apache/incubator-graphar-testing.git /opt/incubator-graphar/testing

导出环境变量：

export GAR_TEST_DATA=/opt/incubator-graphar/testing

在激活虚拟环境后运行官方元数据示例验证（实测回显）：

cd /opt/incubator-graphar/python/example && GAR_TEST_DATA=/opt/incubator-graphar/testing python graph_info_example.py

GraphAr GraphInfo Example
=========================
Graph name: ldbc_sample
Graph prefix: /opt/incubator-graphar/testing/ldbc_sample/parquet/

--- Vertex Info ---
Vertex type: person
Chunk size: 100
Vertex prefix: vertex/person/
Properties:
  Group 0:
    - id: <graphar._core.DataType object at 0x708598342170> (primary: True)
  Group 1:
    - firstName: <graphar._core.DataType object at 0x708598341b70> (primary: False)
    - lastName: <graphar._core.DataType object at 0x708598341b70> (primary: False)
    - gender: <graphar._core.DataType object at 0x708598341b70> (primary: False)

--- Edge Info ---
Edge type: knows
Source type: person
Destination type: person
Chunk size: 1024
Directed: False
Adjacency list types:
  - AdjListType.unordered_by_source: FileType.PARQUET
  - AdjListType.ordered_by_source: FileType.PARQUET
  - AdjListType.ordered_by_dest: FileType.PARQUET
Properties:
  Group 0:
    - creationDate: <graphar._core.DataType object at 0x7085983426b0>

Example completed successfully!

💡 说明：GAR_TEST_DATA 只影响官方示例与测试脚本，SDK 自身的读写 API 不依赖它。该变量是「安装后跑通官方样例」的便捷开关，日常业务代码用不到。

7.3 版本升降级与多版本共存

降级到指定版本（实测从 0.13.0.dev1 降到 0.13.0.dev0）：

/opt/venv-graphar-offline/bin/pip install graphar==0.13.0.dev0

Collecting graphar==0.13.0.dev0
  Downloading graphar-0.13.0.dev0-cp310-cp310-manylinux_2_28_x86_64.whl (22.4 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 22.4/22.4 MB 29.3 kB/s eta 0:00:00
Requirement already satisfied: pyyaml~=6.0 in /opt/venv-graphar-offline/lib/python3.10/site-packages (from graphar==0.13.0.dev0) (6.0.3)
（中间为其余依赖的 Requirement already satisfied 行）
Installing collected packages: graphar
  Attempting uninstall: graphar
    Found existing installation: graphar 0.13.0.dev1
    Uninstalling graphar-0.13.0.dev1:
      Successfully uninstalled graphar-0.13.0.dev1
Successfully installed graphar-0.13.0.dev0

降级后的实测问题：0.13.0.dev0 存在动态链接缺陷，CLI 直接不可用（实测回显）：

/opt/venv-graphar-offline/bin/graphar --version

Traceback (most recent call last):
  File "/opt/venv-graphar-offline/bin/graphar", line 5, in <module>
    from cli.graphar_cli import main
  File "/opt/venv-graphar-offline/lib/python3.10/site-packages/cli/graphar_cli.py", line 24, in <module>
    from graphar._core import (
  File "/opt/venv-graphar-offline/lib/python3.10/site-packages/graphar/__init__.py", line 20, in <module>
    from .graph_info import *
  File "/opt/venv-graphar-offline/lib/python3.10/site-packages/graphar/graph_info.py", line 18, in <module>
    from ._core import DataType, Property, PropertyGroup, AdjacentList, VertexInfo, EdgeInfo, GraphInfo
ImportError: /opt/venv-graphar-offline/lib/python3.10/site-packages/graphar/libgraphar.so: undefined symbol: _ZN5arrow2fs12InitializeS3ERKNS0_15S3GlobalOptionsE

升级恢复（实测用本地 wheel 从 dev0 升回 dev1；在线场景把 --no-index --find-links 参数换成默认源即可，命令形态一致）：

/opt/venv-graphar-offline/bin/pip install --no-index --find-links /tmp/graphar-wheels -U graphar

Looking in links: /tmp/graphar-wheels
Requirement already satisfied: graphar in /opt/venv-graphar-offline/lib/python3.10/site-packages (0.13.0.dev0)
Processing /tmp/graphar-wheels/graphar-0.13.0.dev1-cp310-cp310-manylinux_2_28_x86_64.whl
（中间为依赖的 Requirement already satisfied 行）
Installing collected packages: graphar
  Attempting uninstall: graphar
    Found existing installation: graphar 0.13.0.dev0
    Uninstalling graphar-0.13.0.dev0:
      Successfully uninstalled graphar-0.13.0.dev0
Successfully installed graphar-0.13.0.dev1

多版本共存：pip 不支持同一环境装两个版本，实测推荐用多个虚拟环境隔离（如 /opt/venv-graphar 装 0.13.0.dev1、另一虚拟环境装其他版本），按需切换激活。

八、常见问题（FAQ）

Q1：pip index versions graphar 报 No matching distribution found for graphar，是不是源有问题？ 不是。graphar 只有预发布版本，查询默认排除预发布（实测报错即此原因）。加 --pre 即可看到 0.13.0.dev1、0.13.0.dev0（3.1 节实测回显）；安装时不带 --pre 也能装上（4.2 节实测回显）。

Q2：pip install pygraphar 报错 No matching distribution found for graphscope-client==0.0.1，是 GraphAr 坏了吗？ 不是 GraphAr 的问题——pygraphar 是 GraphScope 的占位包（3.1 节已核实其 home 指向 GraphScope 仓库），本来就装不上。卸掉残留（pip uninstall -y pygraphar），改用正确包名 pip install graphar。

Q3：graphar 运行时为什么不需要 numpy、pandas、pyarrow？ wheel 的声明依赖只有四个（实测读取包元数据）：

grep '^Requires-Dist' /opt/venv-graphar/lib/python3.10/site-packages/graphar-0.13.0.dev1.dist-info/METADATA

Requires-Dist: pydantic<2.12,~=2.0
Requires-Dist: pytest~=7.2
Requires-Dist: pyyaml~=6.0
Requires-Dist: typer~=0.1

Parquet 读写能力由包内捆绑的 C++ Arrow 运行时提供（libgraphar.so 及配套动态库随 wheel 分发），Python 侧不需要 pyarrow；pyarrow 仅在从源码构建 SDK 时才需要（3.3 节）。

Q4：import graphar 报 ModuleNotFoundError 怎么排查？ 两种常见原因：装到了另一个解释器环境（用 pip show graphar 确认 Location，与 python -c "import sys; print(sys.prefix)" 输出比对）；或误装了 pygraphar（模块名是 graphar 不是 pygraphar）。统一在虚拟环境内操作即可避免。

Q5：import graphar 报 undefined symbol: _ZN5arrow2fs12InitializeS3 怎么办？ 这是 0.13.0.dev0 的打包缺陷（7.3 节实测复现），执行 pip install graphar==0.13.0.dev1 恢复即可；后续版本选择时避开 dev0。

Q6：git clone 官方仓库报 GnuTLS recv error (-54) 怎么处理？ 这是 GitHub 访问的网络层报错（克隆 incubator-graphar 时实测出现过）。可重试克隆；持续失败时更换网络环境，或改从官方仓库的 Releases 页面下载源码压缩包。该报错只影响源码与测试数据获取，不影响 pip 安装本身。

九、卸载与清理

卸载包本体（实测）：

/opt/venv-graphar-offline/bin/pip uninstall -y graphar

Found existing installation: graphar 0.13.0.dev1
Uninstalling graphar-0.13.0.dev1:
  Successfully uninstalled graphar-0.13.0.dev1

确认卸载结果：

/opt/venv-graphar-offline/bin/pip show graphar

WARNING: Package(s) not found: graphar

彻底清理：直接删除虚拟环境即可连同依赖一并移除（实测验证目录已不存在）：

rm -rf /opt/venv-graphar-offline && ls /opt/venv-graphar-offline

ls: cannot access '/opt/venv-graphar-offline': No such file or directory

其他清理项：离线 wheel 目录（rm -rf /tmp/graphar-wheels）、测试数据仓库目录、以及实验产出的数据目录（如 /root/graphar-demo、/tmp/import-demo-out），按需删除。pip 缓存可用 pip cache purge 清理。

十、参考链接