跳转到内容
IBKR TWS API 中文实战文档

在 macOS / Linux 上安装 TWS API

macOS / Linux 使用的是官方 Mac / Unix ZIP 包，不是 Windows MSI。

Linux 安装步骤

Section titled “Linux 安装步骤”
  1. 打开官方下载页：Interactive Brokers API Software。
  2. 阅读并同意 TWS API Non-Commercial License。
  3. 下载 Mac / Unix 版本，例如：
twsapi_macunix.MAJOR.MINOR.zip
  1. 打开终端，进入下载目录：
Terminal window
cd ~/Downloads
ls
  1. 解压到用户目录：
Terminal window
unzip twsapi_macunix.MAJOR.MINOR.zip -d "$HOME"
  1. 确认目录存在：
Terminal window
cd ~/IBJts
ls

通常应该能看到 samples 和 source。

macOS 安装步骤

Section titled “macOS 安装步骤”

macOS 也下载 Mac / Unix ZIP 包。官方特别提醒，不要直接双击 ZIP 文件解压；如果系统提示 unsupported format，应使用终端命令解压：

Terminal window
cd ~/Downloads
unzip twsapi_macunix.MAJOR.MINOR.zip

解压完成后再进入 IBJts 或解压出的 API 目录查看 source、samples。

Python API 安装

Section titled “Python API 安装”

进入 Python client 源码目录：

Terminal window
cd ~/IBJts/source/pythonclient
python3 -m pip install .

安装后验证：

Terminal window
python3 -c "import ibapi; print(ibapi.__file__)"

如果项目使用虚拟环境，应先激活虚拟环境，再安装本地源码：

Terminal window
cd /path/to/your/project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install ~/IBJts/source/pythonclient
python -c "import ibapi; print(ibapi.__file__)"

重点是：运行示例代码的 Python，必须和安装 ibapi 的 Python 是同一个环境。

权限和 setuptools 问题

Section titled “权限和 setuptools 问题”

官方文档提到，运行旧命令 python3 setup.py install 时可能遇到：

ModuleNotFoundError: No module named 'setuptools'

也可能因为目录权限出现：

error: could not create 'ibapi.egg-info': Permission denied

更稳的处理方式：

  1. 不优先使用旧的 setup.py install。
  2. 进入 source/pythonclient。
  3. 确认运行安装命令的用户对该目录有写权限。
  4. 使用：
Terminal window
python3 -m pip install .

如果仍然权限不足，再检查目录归属，不要一上来对整个用户目录粗暴授权。

服务器部署提醒

Section titled “服务器部署提醒”

Linux 上安装 TWS API 包，只是让 Python/Java/C++ 代码有客户端库。
它不会自动启动 IB Gateway，也不会替你登录模拟账户。

服务器完整部署还需要：

  • 安装并运行 IB Gateway。
  • 完成登录和 2FA。
  • 开启 API Socket。
  • 配置进程守护、日志、重连和每周认证提醒。

完整服务器部署应把 API 包安装、IB Gateway 启动、登录认证、Socket 端口、进程守护和日志分成不同检查项。不要把“Python 能 import ibapi”误认为“服务器已经能交易”。

常见错误

Section titled “常见错误”
现象常见原因处理方式
No module named ibapi运行脚本的 Python 没有安装 ibapi用同一个 Python 执行 python -m pip install ~/IBJts/source/pythonclient。
Permission denied解压目录或 egg-info 目录无写权限检查目录归属，或把 API 包解压到用户目录。
setuptools 缺失使用旧式 setup.py install优先用 python -m pip install .。
API 包已安装但连不上TWS / IB Gateway 未登录或未开启 Socket API先回到 TWS / IB Gateway 设置和连接测试。

官方依据

Section titled “官方依据”

官方 Install the TWS API on MacOs / Linux 章节说明，Mac / Unix 包会下载为 twsapi_macunix.MAJOR.MINOR.zip 这种形式，Linux 通常解压到 $HOME 后进入 ~/IBJts，macOS 需要用终端 unzip 命令解压。