iSH is an active project to run a Linux shell on iOS. It offers an Alpine Linux environment, complete with the apk package manager. The app relies on usermode x86 emulation.

You can download iSH from the App Store. New installations include a fully functioning apk by default. Existing app users may need to manually install apk following the steps in the documentation.

Getting Started

Begin by installing iSH from the App Store. Launch the app and you’ll be dropped straight into an Alpine Linux terminal environment.

image of the iSH shell for iOS

You can start running familiar Linux commands! You can use all the Unix utilities provided by BusyBox, including cat, grep, ls, sed and wget.

image of using Linux commands in iSH on iOS

iSH provides its own keyboard icon strip to make touchscreen terminal usage simpler. The four buttons to the left of the strip are Tab, Control, Escape and arrow keys respectively. Swipe the arrow key button in the direction you’d like the cursor to navigate.

image of iSH's keyboard

The three buttons on the right open the settings interface, paste text from the iOS clipboard and hide the keyboard. Tap anywhere to bring the keyboard back after hiding it.

iSH Settings

The Settings menu lets you customise a few options. The Appearance page allows you to set the font and switch between light and dark themes. On the App Icon page, you can choose from several app icons. This choice lets you match iSH to the visual style of the other apps on your iOS homescreen.

image of the iSH shell settings menu for iOS

External Keyboard lets you control how iSH should handle a physical keyboard connected over Bluetooth or a USB adapter. In addition to iOS’ built-in remapping options, you can remap the option and backtick keys to the iSH meta and escape keys. You can hide iSH’s icon strip when using an external keyboard by enabling the “Hide with external keyboard” setting.


iSH supports the use of multiple filesystems. Head to the “Filesystems” page in the settings menu to manage them. To start with, you’ll see a single “default” Filesystem containing the builtin Alpine installation.

Press “Browse Files” to open the filesystem in iOS’ Files app. This helps you quickly copy files from iSH to other locations on your iOS device.

image of the iSH shell filesystem settings for iOS

You can export the entire filesystem with the “Export” option. Filesystems can be imported into iSH using the the “Import” button on the main Filesystems page.

The practical use case for filesystems is allowing you to run multiple self-contained installations. At present, only minimal Alpine images similar to the iSH original will work.

You can try Alpine’s “Mini Root Filesystem” – download it, import it and press “Boot From This Filesystem” to restart iSH using the filesystem. Switch back to the default filesystem by selecting its menu entry and again selecting “Boot From This Filesystem”.

Adding Packages

You can use regular apk commands to manage packages in your iSH environment.

# Update the package lists
apk update

# Upgrade existing installed packages
apk upgrade

# Install SSH
apk add openssh

# Remove SSH
apk del openssh

Be aware that iSH defaults to its own package repositories. This allows the app to pass App Store Review by ensuring it’s fully self-contained.

You can switch to the official Alpine Linux repositories if you prefer. This gives you access to the full list of Alpine software. Many packages will have newer versions in the main Alpine repositories than those offered in iSH’s repositories.

grep -v "file:///ish/apk/" /etc/apk/repositories | dd of=/etc/apk/repositories bs=4194304
echo >> /etc/apk/repositories
echo >> /etc/apk/repositories

Run the commands above to replace the contents of iSH’s /ish/apk pseudo-filesystem with the repositories offered by Alpine Linux. You’ll then need to run apk update to get the new package lists.

Using SSH

You can install OpenSSH with apk add openssh.

The client will work immediately – try ssh me@myserver.

To use your iOS device as an SSH server, run the following commands:

ssh-keygen -A
echo "PermitRootLogin yes" >> /etc/ssh/sshd_config

This will generate SSH host keys and prompt you to set a password for the root user. The sshd executable is invoked to start the SSH server. You’ll now be able to connect to your device as the root user.

iSH doesn’t support auto-starting services by default. You can set this up by editing the third line of /etc/inittab to ::sysinit:/sbin/openrc. Next run rc-update add sshd to make the SSH server start automatically when you launch an iSH session.

Running a Web Server

As seen in the SSH example, iSH uses your device’s networking stack. You can host a web server which you’ll be able to browse on your other devices.

Run apk install apache2 to add Apache. Use httpd to start the Apache process. Next, visit your iOS device’s IP address in a web browser – you should see Apache’s default “It works!” text.

Apache running in iSH on iOS

iSH doesn’t currently support running in the background. This means you can’t switch to Safari and browse your webpages while using an iPhone. On an iPad, it’s possible to open a browser in split view – iSH remains active on its side of the screen.

Apache can be configured in the usual way. You’ll find its configuration file at /etc/apache2/httpd.conf. The default document root – where webpages are served from – is /var/www/localhost/htdocs.

What Now?

You’re now running an Alpine Linux environment on your iOS device. Add the packages that make sense for your work. There’s a growing list of working software which includes Unix staples and complete programming languages. Node.js, Python, PHP, Ruby and Git are all operational.

Not every package will work though. Software which makes system calls that haven’t been translated will crash. As iSH is an emulator, performance may also be sub-par at times.

image of using Linux commands in iSH on iOS

You can run a VNC server if you want to use graphical apps. Detailed steps are provided in the iSH wiki. The peformance limitations will become clear with a graphical workload but it is technically possible. The process involves installing xorg-server, setting up a headless configuration and then adding a .xinitrc file to define the window manager to use. You’ll get the best results with a lightweight window manager such as i3.


iSH looks set to become a must-have iOS app for developers and system administrators. There are already quality apps like a-Shell which provide basic Unix tools, as well as SSH clients like Termius which let you connect to a remote Linux machine. iSH is the most complete solution yet though, offering a Linux environment that supports a growing list of popular software.

With iSH on your iPhone or iPad, you can use familiar x86 Linux software wherever you happen to be. Pair it with an external keyboard and you have a portable productivity device that could genuinely replace your laptop.

Profile Photo for James Walker James Walker
James Walker is a contributor to How-To Geek DevOps. He is the founder of Heron Web, a UK-based digital agency providing bespoke software development services to SMEs. He has experience managing complete end-to-end web development workflows, using technologies including Linux, GitLab, Docker, and Kubernetes.
Read Full Bio »