libirecovery: talking to iBoot and iBSS over USB

What the library actually talks to

The libirecovery library allows communication with iBoot and iBSS of iOS devices via USB, and the project describes itself as a cross-platform library which implements communication to the iBoot and iBSS found on Apple's iOS devices via USB, with a command line utility named `irecovery` also provided. The distinction between the library and the utility is worth noting, because they serve different audiences. The library is what a tool like idevicerestore links against, and the utility is what a person types when they need to poke at a device by hand. iBoot and iBSS are the low-level boot components, the stage below the operating system, and talking to them is a different job from talking to a running device over a normal service. That distinction is the reason the usage section starts with a caveat rather than a command.

A fork of openjailbreak.org, and the tool it serves

The README states plainly that this is a fork of an older version from former openjailbreak.org and that it is meant to be used with idevicerestore from the libimobiledevice project. That framing tells you the division of labour in the ecosystem. libirecovery is the low-level transport, the thing that speaks the bootloader's protocol, and idevicerestore is the higher-level tool that decides what to restore and drives the process. The fork's own background is worth noting for a project with this history, since it means the codebase descends from tooling built for jailbreaking and the library inherits both that provenance and the accumulated knowledge of how Apple's bootloaders behave. The topics on the repository list the pieces it covers, with dfu, iboot, ibss, ios, irecovery and library, and the homepage is libimobiledevice.org, which is the project's shared site rather than a separate one.

The build is autotools, and the dependency list is per platform

You need a working compiler, gcc or clang, and a development environment, and the project uses autotools for the build so that the common steps are the same across platforms, with only the prerequisites differing. The hard requirement is libimobiledevice-glue, which some platforms already provide as a package, and the README points at that project's own building section if you need to build it yourself. On Debian and Ubuntu the dependency install is a single apt-get line with build-essential, pkg-config, checkinstall, git, autoconf, automake, libtool-bin, libimobiledevice-glue-dev, libreadline-dev and libusb-1.0-0-dev. On macOS you need the Xcode command line tools, and then either MacPorts or Homebrew to supply automake, autoconf, libtool and the rest. On Windows, MSYS2 is the official way of compiling the project, and the recommended shell is the MSYS2 MinGW 64-bit one, with a pacman line installing base-devel, git, the MinGW gcc, make, libtool, autoconf, automake-wrapper, pkg-config, the MinGW libimobiledevice-glue and the MinGW readline. The README notes you can use a different shell and compiler if you need to and should adapt the command accordingly.

Configuring the tree, from git or from a tarball

You can build from a git checkout or from a `.tar.bz2` release tarball, and the steps differ. Before configuring you need to set the `PKG_CONFIG_PATH` environment variable so that pkg-config can find the dependencies, with a path that uses the same prefix as the dependencies, and the example given is `/usr/local/lib/pkgconfig` for dependencies installed in `/usr/local`. From a git checkout you clone the repository, change into the directory and run `./autogen.sh`. From a release tarball named `libirecovery-x.y.z.tar.bz2` you extract it with `tar xjf` and run `./configure` instead. Both accept options such as `--prefix` to build for a different target folder, and both print a summary at the end showing the install prefix and the USB backend that was selected, along with the reminder to run make and then make install. The USB backend line in the sample output reads IOKit, which is the macOS backend, so the value in the summary tells you which USB implementation your platform selected.

Building and installing, and the ldconfig step

If the configure step printed no errors, the build is a single command:

make

And installation depends on whether the current user can write to the destination directory. Without it, you run `make install`, and with it you run `sudo make install`. The README then adds a Linux specific step that is easy to miss, and you want to run `sudo ldconfig` after installation to make sure the newly installed libraries are picked up by the dynamic linker. That step matters more than it looks, because the failure mode without it is a program that was just installed failing to find its own shared library, which reads as a broken build rather than a missing cache refresh. The build is driven by an autotools Makefile, with `Makefile.am` and `configure.ac` at the top level and an `autogen.sh` script that generates and calls configure.

Using the shell on a device in recovery mode

Usage starts with a precondition: attach the device, and make sure it is not in normal mode. If you need it, the `ideviceenterrecovery` application from libimobiledevice can make the device boot into recovery mode. Then the utility opens a simple shell to interact with the device:

irecovery --shell

The README gives a concrete example of what that is for, and it is the sort of thing that would otherwise be hard to find. To make the device boot into normal mode again you issue three commands in that shell:

setenv auto-boot true
saveenv
reboot

For the full set of options, the README points to the usage information or the manual page, with `irecovery --help` and `man irecovery`. The three command example is worth reading twice, because it shows the shape of the interaction. You are setting an environment variable in the bootloader, saving the environment so the change survives a power cycle, and then rebooting, and the fact that the save step is explicit rather than implicit is the whole point of the shell.

The repository layout and the udev directory

The top level of the repository is a conventional autotools C project, with a `src/` directory for the implementation, an `include/` directory for the public headers, a `tools/` directory, an `m4/` directory for the autoconf macros, a `udev/` directory, a `Makefile.am`, a `configure.ac`, an `autogen.sh` script, a `git-version-gen` helper, a `NEWS` file, a `COPYING` file for the licence and a `README.md`. The `udev/` directory is the one to look at if you are on Linux, since a udev rule is what lets a non-root user talk to a USB device without permissions problems, and it is a detail that the README does not explain in prose. The `git-version-gen` helper is what derives the version string from the git history, which is why the configure summary in the README shows a version that is generated rather than written down. The contributing guidance is standard, with a fork, change, commit and pull request flow, and a request to open a ticket first for larger changes or a major refactoring so that less effort is wasted by everyone.

Where this is the wrong choice

The limits are mostly practical rather than conceptual. First, the device has to be in recovery mode. This is not a tool for talking to a normally running iPhone, and if your goal is to read data off a device, you want a different library entirely. Second, the build is a Unix build system. The Windows path exists but it means MSYS2 and a MinGW toolchain, which is a real cost if your team is Windows native. Third, the platform packages for libimobiledevice-glue are a moving target, since this library depends on it and a stale system package will fail at configure or link time in ways that are not obvious from the error. Fourth, the version is generated from git, so a build from a tarball and a build from a checkout can report different versions, and the configure summary you are given as a sanity check may not match the tag you thought you were building. Fifth, and most importantly, this is infrastructure for one specific ecosystem rather than a general purpose tool, and it exists in the libimobiledevice family alongside idevicerestore, which is where the higher level work lives.

Editorial conclusion

libirecovery fits a developer working at the device recovery layer, restoring an iOS device, or building tooling that has to talk to the bootloader over USB, since it gives you both a library and a working shell utility in one package. It is the wrong tool if you want to talk to a normally booted device, since the device has to be in recovery mode, and the wrong tool if you are on Windows without MSYS2 or a comparable Unix-like build environment. Before you build, install libimobiledevice-glue, which the library requires, and check that your platform package of it is new enough. The last push was on 2026-09-18, version 1.3.1 was released on 2025-10-17, and the licence is LGPL-2.1.

Frequently asked questions

Official sources

1. libimobiledevice/libirecovery on GitHub
2. License: LGPL-2.1
3. Project website
4. README
5. Releases