安装¶

系统要求¶

项目	要求
Python 版本	3.8 及以上
操作系统	Windows 10+、macOS 10.15+、Linux（主流发行版）
架构	x86_64、aarch64（Apple Silicon 原生支持）
网络	需要能访问 PyPI

igapi-rs 提供预编译的二进制 wheel，无需本地安装 Rust 工具链即可直接使用。

标准安装¶

使用 pip 一行命令完成安装：

pip install igapi-rs

若需指定版本：

pip install igapi-rs==0.3.0

推荐：使用虚拟环境¶

# 创建虚拟环境
python -m venv venv

# 激活（Linux / macOS）
source venv/bin/activate

# 激活（Windows CMD）
venv\Scripts\activate.bat

# 激活（Windows PowerShell）
venv\Scripts\Activate.ps1

# 安装
pip install igapi-rs

验证安装¶

安装完成后，运行以下命令验证是否成功：

python -c "import igapi; print('igapi-rs 安装成功')"

预期输出：

igapi-rs 安装成功

若需查看版本号：

import igapi
print(igapi.__version__)

升级到最新版本¶

pip install --upgrade igapi-rs

从源码构建¶

仅当预编译 wheel 不支持你的平台，或需要调试/定制时，才需要从源码构建。

前置依赖¶

依赖	安装方式
Rust 工具链（1.75+）	rustup.rs
maturin	`pip install maturin`
Python 开发头文件	系统包管理器（如 `python3-dev`）

构建步骤¶

# 克隆仓库
git clone https://github.com/open-luban/igapi-rs.git
cd igapi-rs

# 进入 Python 绑定目录
cd src/py

# 开发模式构建并安装（推荐用于本地调试）
maturin develop

# 或构建 wheel 文件后安装
maturin build --release
pip install ../../target/wheels/igapi_rs-*.whl

注意

首次构建需要编译底层代码，根据机器性能可能耗时 2～10 分钟。

常见安装问题 FAQ¶

Q：pip install 报错 "No matching distribution found"¶

原因：当前 Python 版本或操作系统架构暂无预编译 wheel。

解决方案：

升级 pip：pip install --upgrade pip
确认 Python 版本 ≥ 3.8：python --version
若架构不在支持列表，改用从源码构建（见上节）

Q：导入时报错 "ImportError: DLL load failed"（Windows）¶

原因：缺少 Visual C++ 运行时库。

解决方案：下载并安装 Microsoft Visual C++ Redistributable（选择 x64 版本）。

Q：macOS 报错 "Library not loaded" 或 "code signature"¶

原因：Gatekeeper 安全策略阻止未签名二进制。

解决方案：

# 清除隔离标记
xattr -d com.apple.quarantine venv/lib/python*/site-packages/igapi/*.so

Q：安装成功但 `import igapi` 失败¶

可能原因及解决方案：

虚拟环境未激活：确认命令行前缀有 (venv) 标识
安装到了错误的 Python：使用 python -m pip install igapi-rs（而非直接 pip）
包名混淆：PyPI 包名是 igapi-rs，但导入时使用 import igapi（无连字符）

验证当前 Python 对应的 pip：

python -m pip show igapi-rs

Q：安装速度慢¶

解决方案：使用国内镜像源：

# 临时使用
pip install igapi-rs -i https://pypi.tuna.tsinghua.edu.cn/simple

# 永久配置
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Q：maturin develop 报错 "linker not found"（Linux）¶

解决方案：安装编译工具链：

# Ubuntu / Debian
sudo apt-get install build-essential python3-dev

# CentOS / RHEL
sudo yum groupinstall "Development Tools"
sudo yum install python3-devel

安装¶