> ## Documentation Index
> Fetch the complete documentation index at: https://ios-on-switch.brunostjohn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> From an empty partition on your SD card to the iPadOS Home Screen.

> [!WARNING]
>
> Nobody can help you if this goes wrong. Copy everything on your SD card somewhere safe before you start, because
> partitioning a card can wipe it.

## What you need

* A Switch OLED that already boots [hekate](https://github.com/CTCaer/hekate). Getting a console to that point is
  its own project, and these docs don't cover it.
* A microSD card with room for a partition of 32 GB or more for iOS, plus space on the card's FAT partition for
  the install image while it's being copied.
* A Mac running macOS, on Apple silicon or Intel, with about 35 GB free, an internet connection and an
  administrator password.
* [Bazelisk](https://github.com/bazelbuild/bazelisk) on that Mac. It's the only thing the image builder needs.

To install Bazelisk, paste this into Terminal. It works on Apple silicon and Intel Macs.

```bash theme={null}
sudo mkdir -p /usr/local/bin
sudo curl -fL -o /usr/local/bin/bazelisk https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-darwin
sudo chmod +x /usr/local/bin/bazelisk
```

If you already use Homebrew, `brew install bazelisk` does the same thing.

## Install iOS

**1. Make a partition for iOS in hekate**

Boot hekate and open **Tools**, then **Partition SD Card**. Make a Linux or an Android partition at the size you
want iOS to have, and let hekate finish.

Don't install Linux or Android onto it afterwards. The installer turns that partition into iOS's and leaves every
other partition alone. Pick the size now: the image is built for this exact partition, so if you repartition
later, you build it again.

**2. Get the source**

Open the project's [releases](https://github.com/brunostjohn/ios-on-switch-lmao/releases), download **Source code
(zip)** for the latest release and double-click it to unzip it. Then open Terminal in the unzipped folder.

**3. Build the image and copy it to the card**

Put the SD card in your Mac and run:

```bash theme={null}
bazelisk run //:image -- --copy-to-card
```

The builder finds the Switch card, reads the size of the partition you just made, downloads iPadOS from Apple and
the release's prebuilt parts, and builds an image that fits that partition exactly. It asks for your password once,
to set file owners inside the image. The first run downloads several gigabytes, so give it time.

It then copies its files onto the card and ejects it. It only adds `switchroot/ios/`, `bootloader/ini/ios.ini`,
`bootloader/res/icon_ios.bmp` and `bootloader/payloads/install-ios.bin`, and leaves everything else on the card
alone.

> [accordion] Options
>
> Put these after `--`, as in `bazelisk run //:image -- --copy-to-card --disk disk4`.
>
> | Option | Use it when |
> | - | - |
> | `--disk diskN` | More than one card is in the Mac. `diskutil list external` shows which is which. |
> | `--partition NAME` | The card has both a Linux and an Android partition. |
> | `--size 64G` | The card isn't in the Mac. Give the partition's exact size. |
> | `--out DIR` | You want the build's folder somewhere other than `out/sd` in the source folder. |
>
> `bazelisk run //:image_dry_run -- --size 64G` checks the card or the size and prints the plan without
> downloading the large files.

> [accordion] Copying the folder yourself
>
> Without `--copy-to-card`, the builder stops after writing its folder and prints where it is. Everything in it
> goes onto the root of the SD card, merged with the `bootloader` and `switchroot` folders already there.
>
> Don't drag it over in Finder. Finder offers to replace folders that already exist, which would delete hekate's.
> `ditto` merges instead. Put your card's name in place of `SWITCH SD`:
>
> ```bash theme={null}
> ditto --norsrc --noextattr out/sd "/Volumes/SWITCH SD"
> diskutil eject "/Volumes/SWITCH SD"
> ```

**4. Run the installer**

Put the card back in the Switch, boot hekate and open **Payloads**, then **install-ios.bin**.

The installer shows the image and the partition it will replace, with their names and sizes. If more than one
partition fits, move between them with the volume buttons and press POWER to pick one. On the last screen,
VOL+ erases that partition and installs iOS, and VOL- cancels without writing anything.

A progress bar counts the megabytes written. When it finishes, it says iOS is installed and deletes the image from
the card to give you the space back. Press POWER to go back to hekate.

If the image doesn't match the partition's size, the installer shows both sizes and refuses before it writes
anything. Build the image again with the card in the Mac.

**5. Boot iOS**

In hekate, open **More Configs** and pick **iOS**.

The first boot takes several minutes. The Apple logo stays on screen with iPadOS's progress bar under it while
the system sets itself up and installs its built-in apps. Later boots go from the logo straight to the Home Screen.

## Updating

Build the new release's image and install it the same way. For now that erases everything you had in iOS.

## Removing it

Delete or recreate the iOS partition with hekate's partition manager. Then delete these from the SD card:

* `switchroot/ios/`
* `bootloader/ini/ios.ini`
* `bootloader/res/icon_ios.bmp`
* `bootloader/payloads/install-ios.bin`

The installer never touches anything else on the card.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.