Jonathans Blog

Stylish mechanical keyboard with colorful keycaps on wood desk, vibrant workspace.

How to Install Packages in iSH with apk

Jonathan Mitchell
· ·

The goal: a useful Linux toolbox on your iPhone

If you followed my guide to running a Linux shell on iPhone with iSH, you have a working shell but not much in it. iSH runs a small Alpine Linux userland under x86 emulation, so the way to install packages in iSH is Alpine’s own package manager, apk. This post covers how iSH’s repositories differ from a normal Alpine box, how to find things, and a sensible starter set that won’t eat your storage.

How iSH repositories work

The App Store build of iSH (version 1.3.2 at the time of writing, last updated in 2023) is based on Alpine 3.14. Rather than pointing at the live Alpine mirrors, it uses a frozen snapshot of the 32-bit x86 repositories that the iSH project maintains, so packages match what the emulator can actually run. You can see what you’re using with:

cat /etc/apk/repositories

You’ll see a dated release string along the lines of v3.14-2023-08-15. The iSH wiki notes that TestFlight beta builds have moved to a newer Alpine base (3.19 by default as of early 2026), so check this file rather than assuming.

Two things to know before you tinker:

  • If the /ish directory exists, iSH rewrites /etc/apk/repositories back to its own snapshot whenever you run apk update.
  • Pointing iSH at official Alpine mirrors is possible (the wiki has a guide), but only do it after a backup, and keep the release version matching the one you’re actually running.

The everyday apk commands

Start every session where you plan to install things by refreshing the index:

apk update

Then the handful of commands you’ll use constantly:

apk search ripgrep        # find packages by name
apk add ripgrep           # install
apk info -a ripgrep       # details, size, dependencies
apk del ripgrep           # remove
apk upgrade               # upgrade everything installed

apk search matches substrings, so apk search python3 returns a long list. Add -v to see descriptions, which helps when names are cryptic.

A sensible starter set

Everything runs under emulation, so a lean install is a fast install. These are the packages I add first:

  • vim or nano for editing (both are on the iSH wiki’s list of things that work)
  • git and openssh-client for code and remote servers, covered in SSH and git on iPhone with iSH
  • curl and wget for fetching files over HTTPS
  • jq for poking at JSON APIs
  • tmux so long-running jobs survive you switching apps
  • bash or zsh if BusyBox’s ash feels too bare
  • python3 when you need scripting, see Python and Node in iSH

You can add several in one go:

apk add vim git openssh-client curl jq tmux

If you’ve set up a shell on Android before, the approach is the same as my zsh and Oh My Zsh in Termux guide: install the minimum, then customise.

Keeping iSH small

iSH’s filesystem lives inside the app’s storage, and every package adds to it. A few habits help:

  1. Use apk add --virtual .build gcc musl-dev for temporary build dependencies, then apk del .build to remove the whole group when you’re done.
  2. Run apk cache clean occasionally if you’ve enabled a cache.
  3. Check what’s taking space with du -sh /usr/lib/* | sort -h | tail.
  4. Don’t install desktop or X11 packages. Many fail with illegal instruction errors anyway.

Troubleshooting and limitations

  • Downloads stop part way: the wiki notes that resizing the terminal (rotating the phone, for example) can cancel a running download. Keep the phone still and rerun the command.
  • "Illegal instruction": the binary uses CPU features iSH doesn’t emulate. Look for an alternative package; there’s no flag that fixes it.
  • 64-bit only software: iSH emulates 32-bit x86 and can’t run 64-bit ELF binaries, so random prebuilt downloads from the web usually won’t work. Stick to apk.
  • Package missing: the 3.14 snapshot is old, so newer tools may simply not be there. Check the wiki’s "What works?" page before going down a rabbit hole.
  • apt, dpkg, brew: none of these work in iSH. apk is the only supported route.

Wrapping up

Learning to install packages in iSH with apk is what turns it from a novelty into a proper pocket toolbox. Update the index, install only what you need, and keep an eye on the repository file if you experiment with newer Alpine mirrors. Next up, put those tools to work over the network.

iSH: Linux on your iPhone series. Start with the original guide to running a Linux shell on iPhone with iSH, then:

  1. Installing packages in iSH with apk
  2. SSH and git on iPhone with iSH
  3. Python and Node in iSH
  4. iSH vs a-Shell vs Blink Shell
  5. Accessing iOS files in iSH
,

Leave a Reply