LinuxRunner

LinuxRunner can be installed on compatible iPhones and iPads using a supported IPA signing method.

The application requires an ARM64 device with iOS or iPadOS 15.0 or later.

Installation steps:

1. Open Settings → General → About on your iPhone or iPad.
2. Check your installed iOS or iPadOS version.
3. Confirm that your device supports ARM64 applications.
4. Visit the official LinuxRunner GitHub repository.
5. Open the Releases section.
6. Select LinuxRunner v1.0.1.
7. Download LinuxRunner-1.0.1.ipa.
8. Check its SHA-256 checksum against the official release information.
9. Open Sideloadly, AltStore Classic or another compatible IPA signing tool.
10. Import the downloaded LinuxRunner IPA.
11. Follow the signing and provisioning instructions.
12. Install the application on your iPhone or iPad.
13. Enable Developer Mode if your installation method requires it.
14. Open LinuxRunner from the Home Screen.
15. Select the Distributions tab.
16. Tap Set Up Linux and follow the setup wizard.
17. Choose Debian, Arch Linux ARM or Alpine.
18. Install the selected distribution and configure a Linux user account.
19. Open Terminal to start using supported Linux commands.

How to install Debian Linux in LinuxRunner

Debian GNU/Linux 13 ARM64 is the developer's recommended starting point.

1. Open LinuxRunner.
2. Select Distributions.
3. Tap Set Up Linux.
4. Choose Debian GNU/Linux 13 ARM64.
5. Follow the installation wizard.
6. Keep LinuxRunner in the foreground while it downloads and configures the environment.
7. Restart the application if the installer requests a relaunch.
8. Create a Linux username and password.
9. Enable administrator access if you need sudo.
10. Open Home → Terminal.

After setup, you can check the installed Linux distribution using:

cat /etc/os-release

Check the processor architecture using:

uname -m

The architecture should normally be reported as aarch64.

How to install Arch Linux ARM

Open Distributions → Set Up Linux and choose Arch Linux ARM.

Complete the installation and use pacman to manage supported packages.

Arch's desktop environment is experimental and uses Openbox, LXQt Panel and PCManFM-Qt.

How to install Alpine Linux

Choose Alpine Linux 3.24 ARM64 from the distribution setup screen.

Alpine is better suited to smaller terminal-focused environments.

Use apk to install supported packages.

How to open a Linux desktop

After configuring a distribution, install its desktop components using the available LinuxRunner setup option.

Select Open Desktop to start a graphical session.

On the touchscreen, tap for a left click, long-press for a right click and use supported gestures to pan or zoom.

Can LinuxRunner be installed without a computer?

A compatible on-device signing method may work if it can correctly sign and provision the IPA.

The developer specifically documents Sideloadly and AltStore Classic as installation examples.

Important update warning

When installing a newer version, preserve the application's bundle identifier and App Group configuration.

Back up important Linux files before updating.

Do not uninstall LinuxRunner merely to fix a startup issue, because uninstalling may delete the stored Linux environments.

LinuxRunner allows users to run supported ARM64 Linux software inside an iOS application.

ARM64 Linux Interpreter

LinuxRunner interprets supported ARM64 Linux instructions and supplies compatibility functions for required Linux system calls.

No Full Linux Kernel Required

The application does not boot a Linux kernel or replace iOS.

No Jailbreak Required

LinuxRunner can be sideloaded on compatible devices without modifying the operating system through a traditional jailbreak.

No JIT Required

The release build does not depend on JIT execution.

No Virtual Machine Required

LinuxRunner does not use QEMU or hardware virtualization to boot a virtual computer.

Debian GNU/Linux 13

Install a Debian ARM64 environment with compatible shell utilities, packages and the apt package manager.

Arch Linux ARM

Run Arch Linux ARM using pacman.

Version 1.0.1 improves package recovery and supports an experimental graphical desktop.

Alpine Linux 3.24

Install a lightweight Alpine ARM64 environment using apk.

Alpine is useful for command-line tools and smaller workloads.

Linux Terminal

Open a Linux terminal to run supported command-line programs.

Package Managers

Install compatible ARM64 packages using apt, dpkg, pacman or apk, depending on the chosen distribution.

Developer Tools

Experiment with available ARM64 builds of compilers, Python, Node.js and other command-line development tools.

Not every toolchain or package will work correctly.

Multiple Linux Environments

Install more than one supported distribution.

Each environment maintains its own files, packages and settings.

Only one Linux runtime is active per application launch.

Graphical Linux Desktop

LinuxRunner provides X11 desktop support with windows, desktop controls and application launching.

KDE Plasma

Debian includes an experimental KDE Plasma desktop option.

Performance and compatibility vary by device.

Openbox and LXQt Components

Arch Linux ARM includes an experimental desktop using Openbox, LXQt Panel and PCManFM-Qt.

This is not a claim of complete LXQt or Plasma support.

Linux Desktop Applications

The project demonstrates or documents experiments with applications such as Firefox, Chromium, Dolphin, Konsole and Blender.

These applications may encounter unsupported system calls, graphics limitations or excessive memory consumption.

Telegram Desktop

The developer reports successfully testing Telegram Desktop on Arch Linux ARM, including login, messaging and calls.

Background notifications and uninterrupted calling should not be assumed because iOS can suspend LinuxRunner.

Touch Controls

Interact with supported graphical applications using touch gestures.

Hardware Keyboard Support

Use a compatible hardware keyboard to interact with the Linux terminal and desktop.

Mouse and Trackpad Input

Supported pointer events allow interaction with desktop windows and applications.

iPad Desktop Adaptations

Version 1.0.1 adds window-aware sizing, desktop shortcuts and improved interface controls for iPad.

File Import and Export

LinuxRunner supports importing and exporting files between accessible application storage locations and Linux environments.

Shared Folders

Optional shared-folder functionality allows supported file exchange, subject to iOS permissions.

Networking

LinuxRunner provides a Linux socket compatibility layer using supported iOS networking capabilities.

Mesa Software Graphics

Graphical applications can use Mesa-based software OpenGL rendering.

Experimental Metal Acceleration

The developer documents an experimental Metal bridge for selected graphics operations.

Hardware acceleration is not guaranteed.

Desktop Session Recovery

Version 1.0.1 improves desktop session reopening and recovery after certain component crashes.

Package Recovery

Arch Linux ARM receives improved signed package caching and recovery.

Supported iOS Versions

1. iOS 14 - iOS 27 +

Supported Devices

LinuxRunner is designed for ARM64 iPhones and iPads.

The developer reports successful graphical operation on a physical iPhone and has physically tested iPad support.

Unsupported Applications and Environments

LinuxRunner does not currently support:

1. x86 or x86-64 Linux applications
2. Booting a Linux kernel
3. Kernel modules
4. systemd as the init system
5. Conventional Linux containers
6. Wayland desktop sessions
7. Arch Plasma desktop sessions
8. Windows applications as native Linux programs

Performance Limitations

LinuxRunner uses interpretation and compatibility layers, so performance may differ significantly from native Linux hardware.

Memory-heavy applications can fail or be terminated by iOS.

Background Limitations

iOS can suspend or terminate LinuxRunner when it leaves the foreground.

Saved files may persist, but active Linux processes do not survive application termination.

Security Limitations

Linux users and permissions inside LinuxRunner do not provide a strong security boundary against malicious programs running within the same application.

Do not execute untrusted Linux binaries or scripts that could access personal data exposed to the LinuxRunner environment.

If LinuxRunner is not installing, launching Linux or opening desktop applications, check the following problems.

LinuxRunner IPA Is Not Installing

The release IPA is ad-hoc signed but does not include an Apple provisioning profile.

Use a compatible IPA signing tool to complete installation.

LinuxRunner App Is Not Opening

Check the app signature, firmware requirements and device compatibility.

An unresolved black-screen issue has been reported on an iPhone 11 running iOS 17.

LinuxRunner Shows a Black Screen

Check the official GitHub issue tracker for device-specific fixes.

Do not delete the app without first backing up any important Linux data.

Developer Mode Is Required

Some sideloading methods require Developer Mode.

Open Settings → Privacy & Security → Developer Mode and follow Apple's instructions.

Linux Distribution Is Not Installing

Check your internet connection, available storage and the selected distribution.

Keep LinuxRunner in the foreground while installation is running.

Setup Requests an App Restart

Close LinuxRunner using the app switcher and reopen it.

Follow the setup wizard to continue installing or configuring the environment.

Debian Terminal Is Not Opening

Confirm that Debian setup finished and that a valid Linux account has been created.

Arch Linux Packages Are Not Installing

Check the pacman package database and network connection.

Version 1.0.1 improves signed package recovery and related compatibility behavior.

Alpine Linux Packages Are Missing

The selected package may not be available for Alpine's ARM64 repositories.

Search for a compatible package or build it from supported sources.

Linux Desktop Is Not Starting

Confirm that the desktop components were installed for the selected distribution.

Some desktop configurations remain experimental and can fail during startup.

KDE Plasma Is Not Working

KDE Plasma support is experimental.

Try the simpler LinuxRunner Desktop or use a terminal-based workflow.

Arch Linux Desktop Shows Missing Components

The supported Arch desktop uses selected Openbox and LXQt components rather than a full desktop distribution.

Firefox or Chromium Crashes

Browsers may require unsupported Linux functionality or more memory than iOS allows.

Try a smaller workload or a different supported application.

Blender Is Not Running Correctly

Blender can use significant memory and graphics resources.

Simple demonstration scenes may work, but complex projects can exceed the available limits.

Telegram Desktop Is Not Working

The maintainer reports successful testing on Arch Linux ARM.

Check the installed package, network availability and Linux distribution setup.

Do not expect desktop notifications to keep working after iOS suspends LinuxRunner.

LinuxRunner Cannot Run an x86 Application

Only ARM64 Linux userspace programs are supported.

Applications compiled exclusively for x86 or x86-64 are not compatible.

LinuxRunner Cannot Start systemd

LinuxRunner does not boot a normal Linux kernel or support systemd as init.

Use compatible process-management methods where available.

LinuxRunner Wayland Session Is Not Starting

Wayland sessions are not supported in the current release.

Use the documented X11 desktop environment.

Graphics Are Slow

Mesa software rendering and CPU instruction interpretation can be demanding.

Experimental Metal acceleration may help selected paths but is not guaranteed.

LinuxRunner Stops Running in the Background

iOS can suspend or terminate background applications.

Keep LinuxRunner in the foreground for important interactive sessions and long-running tasks.

Linux Files Disappeared After Reinstalling

Uninstalling the application may delete stored Linux environments.

Preserve the app's identity and back up important files before updating.

LinuxRunner Uses Too Much Storage

Linux distributions and installed packages require additional space beyond the IPA itself.

Remove unnecessary packages or environments after backing up important data.

LinuxRunner Overheats the Device

Interpreting Linux instructions and rendering graphical applications can create substantial CPU load.

Reduce the workload and stop intensive sessions if the device becomes unusually hot.

Safety Tips

Install LinuxRunner from the official GitHub release.

Verify the original IPA checksum before signing it.

Avoid running untrusted Linux programs because Linux guest permissions are not a complete security boundary.

Keep backups of important Linux files and test demanding applications on a device with sufficient memory and storage.