Skip to main content

Installation

idb is made up of 2 parts, both of which are installed by a single brew formula.

idb companion​

The companion runs on macOS only, next to the Simulators and Devices it automates. Each target (simulator/device) will have a companion process attached, allowing idb to communicate with it remotely.

The idb companion can be installed via brew or built from source:

brew install facebook/fb/idb

Notes:

  1. Instructions on how to install brew can be found here

  2. The brew formula installs a prebuilt companion binary — nothing is compiled on install. It requires an arm64 Mac running macOS 15 or later, with a full installation of Xcode 26 or later selected. Installing just the Command Line Tools is not sufficient. Xcode can be installed from the App Store.

idb client​

A cli tool and python client library is provided to interact with idb. It can run on any OS with a Python installation — it does not need to run on the Mac that hosts the companion.

It is installed alongside the companion by the brew formula above. It can also be installed separately via pip (releases publish to PyPI):

pip3 install fb-idb

Note: The idb client requires python 3.10 or greater to be installed.

Note: Instructions on how to install pip can be found here

Installing a specific build​

Besides the stable formula, any idb release, and the CI build of any commit whose CI run passed, can be installed through Homebrew with homebrew.py at the root of the repository. It needs only the Python that ships with macOS:

git clone https://github.com/facebook/idb.git && cd idb
./homebrew.py builds                 # releases and recent CI builds of main
./homebrew.py install v1.6.2         # a release
./homebrew.py install 1a2b3c4        # the CI build of a commit (or a branch)
./homebrew.py install pr:123         # the CI build of a pull request
./homebrew.py status                 # what is installed, and which build it is
./homebrew.py uninstall --restore    # back to facebook/fb/idb
./homebrew.py                        # pick a build interactively

Builds are installed from a separate local tap, idb-local/builds, and replace an installed facebook/fb/idb after asking. CI builds carry version 0.0.0; status shows the commit and CI run they came from. Downloading a CI build needs a GitHub token, even though the repository is public: set GITHUB_TOKEN, or log in with the GitHub CLI (gh auth login). A CI build can be installed until its run's artifacts expire.

Make sure both parts of idb are installed successfully and then you're good to go! Head over to the guided tour to try idb out.