How to install Rockbox on your iPod

NOTE: This page is a work-in-progress set of instructions for a new streamlined ipod install procedure using the new ipodpatcher tool. It is a single set of instructions for all users (Windows, Mac OS X and Unix). Once these instructions are completed, they should be moved to the manual and this wiki page deleted.

NOTE: These instructions are known to have problems with the 1st and 2nd Generation Mini and 4G (Greyscale) ipods - Rockbox loads correctly, but the original Apple firmware will not start. If you have one of these ipods, you should continue using the old installation instructions at the IpodPort page.

Notes before installing

Which ipods does Rockbox work on?

Rockbox only works on the following ipods:

• 3rd Generation (but with poor performance)
• 4th Generation Greyscale
• 1st and 2nd Generation Mini
• Photo/Color
• 1st Generation Nano (NOT the current, 2nd Generation, Nano with all-aluminum body)
• 30GB and 60GB Video (NOT the 80GB model)

Rockbox does not work on the Shuffle (both old and new), the new "2nd Generation" ipod Nano (the all-aluminium version) or the 80GB ipod Video. The 1st and 2nd Generation ipods (the very first ipod models) are not supported and Rockbox works but with poor performance on the 3rd Generation ipod.

For more information on identifying which ipod you own (information you need to know in order to install Rockbox), see this page from Apple's website: Identifying Different iPod Models.

In addition to the above requirements, Rockbox only works on ipods formatted with the FAT32 filesystem (i.e. ipods initialised by iTunes for Windows). It does not work with the HFS+ filesystem (i.e. ipods initialised by iTunes for the Mac). More information and instructions for converting an iPod to FAT32 can be found on the IpodConversionToFAT32 wiki page. Note that after conversion you can still use a FAT32 ipod on a Mac.

Installation instructions

[NOTE: Give a short overview of how Rockbox on ipod works - i.e. Apple bootloader is safe in flash and that bootloader loads the firmware from the hard disk. Rockbox inserts a second bootloader on the hard disk so that when the ipod is started, that bootloader is run instead of the normal Apple firmware. The Rockbox bootloader then loads either Rockbox or the original Apple firmware. Maybe also a note about how ipods can always be restored even with completely corrupted hard disk contents, so Rockbox on an ipod is low risk]

Step 1 - Install Rockbox

a) Download rockbox.zip and rockbox-fonts.zip for your iPod

Rockbox is in constant development - new versions of Rockbox are automatically compiled every time a source file is changed in the Rockbox CVS source code repository.

You need to download download the current build (updated on every source change). You MUST ensure that you download the correct version of Rockbox for your iPod.

b) Unzip rockbox.zip and rockbox-fonts.zip to your iPod

The rockbox.zip you have downloaded contains the Rockbox firmware itself (a file called rockbox.ipod) plus a support directory containing configuration files, plugins, audio codecs, fonts and themes. This directory is called ".rockbox" (note the dot at the start of the name).

To install (or upgrade) Rockbox you need to attach your iPod to your PC via USB or Firewire, ensure that iTunes is set up to allow you to access your ipod as a disk, and then unzip both rockbox.zip and rockbox-fonts.zip to the top-level (root) folder on your iPod.

NOTE: Make sure (if you are using any Windows OS earlier than Windows 2000) that you eject the iPod with the "Unplug or Eject Hardware" (found in the system tray next to the clock) before unplugging it, or there will almost certainly be corrupted files and Rockbox will act up! However, there is no need to eject your ipod yet - just go to Step 2 and install the bootloader.

Step 2: Install the bootloader

In order to make your iPod load and execute the Rockbox firmware you have just installed, you will need to install the Rockbox bootloader. Unless bugs are found in the bootloader code, or significant new feature are added, you will only have to perform this step once.

These steps use the ipodpatcher tool. Source code is available in the Rockbox SVN (see UsingSVN).

a) Bootloader installation from Windows

1. Make sure you are logged into your computer as Administrator, or a user with Administrator privileges and connect your ipod.
2. Download ipodpatcher.exe and run it.
3. If all has gone well, you should see some information displayed about your ipod and a message asking you if you wish to install the Rockbox bootloader. Press y followed by ENTER, and ipodpatcher will now install the bootloader. After a short time you should see the message "[INFO] Bootloader installed successfully." Press ENTER again to exit ipodpatcher.
4. Disconnect your ipod in the usual way. The bootloader is now installed.

b) Bootloader installation from Mac OS X

1. Attach your ipod to your Mac and wait for its icon to appear in Finder. If you have configured itunes to open automatically when your ipod is attached (the default behaviour), then wait for it to open and then quit it. You also need to ensure the "Enable use as disk" option is enabled for your ipod in itunes.
2. Open up Disk Utility (in Applications -> Utilities) and click on the name of your ipod (e.g. DAVE_S IPOD) in the list on the left pane. Then click on the "unmount" icon at the top. NOTE: DO NOT click on the "eject" icon.
3. Download and open ipodpatcher.dmg and then double-click on the ipodpatcher icon inside. 1. If all has gone well, you should see some information displayed about your ipod and a message asking you if you wish to install the Rockbox bootloader. Press y followed by ENTER, and ipodpatcher will now install the bootloader. After a short time you should see the message "[INFO] Bootloader installed successfully." Press ENTER again to exit ipodpatcher and then quit the Terminal application.
4. NOTE: If you received a "Resource busy" error from ipodpatcher, then this means you didn't complete step 2). Go back to Disk Utility, unmount your ipod and then run ipodpatcher again.
5. Your ipod will now automatically reconnect itself to your Mac. Wait for it to connect, and then eject and unplug it in the normal way. NOTE: You should unplug your ipod immediately after ejecting it to prevent Rockbox immediately rebooting your ipod into disk mode when it detects that your ipod is attached to a computer.

c) Bootloader installation from Linux

1. Download ipodpatcher (32-bit x86 binary or 64-bit amd64 binary). You can save this anywhere you wish, but the next steps will assume you've saved it in your home directory.
2. Attach your ipod to your computer.
3. Open up a terminal window and type the following commands:

      cd $HOME
      chmod +x ipodpatcher
      ./ipodpatcher

   NOTE: You may need to be the root user in order for ipodpatcher to have sufficient permission to perform raw disk access to your ipod.
4. If all has gone well, you should see some information displayed about your ipod and a message asking you if you wish to install the Rockbox bootloader. Press y followed by ENTER, and ipodpatcher will now install the bootloader. After a short time you should see the message "[INFO] Bootloader installed successfully." Press ENTER again to exit ipodpatcher.
5. Disconnect your ipod in the usual way. The bootloader is now installed.

Step 3 - Download and read the manual

Rockbox behaves very differently to Apple's firmware. A user manual (updated every night) is available here:

• http://www.rockbox.org/manual.shtml

Common questions asked by users new to Rockbox on the ipod are answered here:

• IpodFAQ