Skip to content

Instantly share code, notes, and snippets.

@TheZoc
Last active October 6, 2024 13:47
Show Gist options
  • Save TheZoc/849a82d3eed219998cd82fb4040607ae to your computer and use it in GitHub Desktop.
Save TheZoc/849a82d3eed219998cd82fb4040607ae to your computer and use it in GitHub Desktop.
This is a guide to setup Arch Linux in Raspberry Pi 4, using macOS as the auxiliary system.

Raspberry Pi Setup Guide

This guide will use either a macOS or an ArchLinux base system, to prepare a microSD card with Arch Linux for Raspberry Pi.

If someone managed to do the initial setup using Windows, please let me know, so I can add to this guide.

This guide will be verbose at times for some simple tasks. This is intended to help people just starting out, so it's not confusing. If something confuses you, let me know and I'll try my best to answer it.

Special thanks to karog on ArchLinuxARM forums for their contributions on improving this guide!

Information about the ARM 64-bit architecture

The aarch64 (ARM 64-bit architecture) is not officially supported at the writing of this guide. The official arm image we will be using uses armv7h (32 bits).

If you want to use an unoficial image that support sthe 64-bit architecture, you can find it in this forum topic.

You can follow all the steps in this guide and just need to replace the images when the time come, in Part 1, Step 15 of this guide.

What you will need

  • A target Raspberry Pi. I used a Raspberry Pi 4 8GB model.
  • A base system that is either:
    • macOS
    • PC running ArchLinux
    • Raspberry Pi running ArchLinux
  • A USB microSD Card reader. Do NOT use the macOS built in SD Card reader! You won't be able to edit partitions if you do!
  • A microSD Card. I used a 256GB one, but anything over 16GB should work.
  • Patience
  • For macOS Only: Paragon extFS for macOS. The Trial version is fine for this guide.

Part 1: microSD Preparation

For the preparation you can use either a macOS base system or an ArchLinux base system. Select the appropriate section for your system below. Keep in mind this setup will wipe the contents of the microSD card!

Using macOS to prepare the microSD

  1. Insert the microSD card in the USB reader, and insert the reader in your mac. Again: Do NOT use the built in SD reader!
  2. Open Disk Utility and check what is the device name for your microSD card. Here it is disk2, so I will be using this name on this guide. You might need to click the "View" icon and set "Show all devices".
  3. From the last step, my microSD is disk2, so I will be using /dev/disk2. Replace accordingly, if following this guide! I am not responsible for data loss!
  4. Unmount the volumes using Disk Utility. Do NOT eject the device, only unmount the volumes. They will appear greyed out after unmounting.
  5. sudo fdisk -i /dev/disk2. This will initialize a new MBR on your microSD. This will destroy all data!
  6. sudo fdisk -e /dev/disk2. This will enter fdisk in "edit in interactive mode".
  7. Type print and press enter. If you see the table below with 4 unused fields, you can type quit and proceed to step 12.
         Starting       Ending
 #: id  cyl  hd sec -  cyl  hd sec [     start -       size]
------------------------------------------------------------------------
 1: 00    0   0   0 -    0   0   0 [         0 -          0] unused
 2: 00    0   0   0 -    0   0   0 [         0 -          0] unused
 3: 00    0   0   0 -    0   0   0 [         0 -          0] unused
 4: 00    0   0   0 -    0   0   0 [         0 -          0] unused
  1. Type erase and press enter.
  2. Type write and press enter.
  3. Type print and press enter. This should give you the table displayed in step 7.
  4. Type quit and press enter.
  5. Here, we're done with the fdisk step. If you're coming from step 7, this is the right step to proceed on.
  6. Now we need to format a 512Mb FAT32 partition for booting, and an ext4 partition with the rest of the space available to store out files.
  7. Run sudo diskutil partitionDisk /dev/disk2 MBR fat32 "boot" 512m UFSD_EXTFS4 "root" 0b, and wait until completion. You will need Paragon extFS installed for this step.
  8. Download the version you want to run in your Raspberry pi to your favourite directory. In my exampe, I downloaded it to ~/Downloads.
  9. Once the formatting is done, go to Disk Utility and eject the device. Remove the USB Card Reader, take a deep breath and reinsert it. Yes, the deep breath is important :)
  10. cd /Volumes/root
  11. sudo tar -xpf ~/Downloads/ArchLinuxARM-rpi-4-latest.tar.gz. Remember to use the correct file name you downloaded in the step 15. Wait until it's fully decompressed.
  12. sudo mv boot/* ../boot
  13. sudo sync
  14. If you decided to download AArch64 version, you need to run this command:
sudo sed -i 's/mmcblk0/mmcblk1/g' etc/fstab
  1. Eject the devide using Disk Utility.

Done! You have a barebones ArchLinux install in your microSD!

Using ArchLinux to prepare the microSD

All the steps below must be done as root.

  1. Get the necessary tools to partition and format the microSD card:
pacman -S sudo
pacman -S dosfstools
  1. Use lsblk to check the storage devices currently attached to the system.
  2. Insert the microSD card in the USB reader, and insert the reader in your system.
  3. Use lsblk again. See what is the new drive attached since step 2. Here, the microSD card received the name sda, and I'll use it for the rest of this guide.
  4. Use sudo fdisk /dev/sda to start partitioning the card. Be sure to use the correct device from step 4 before proceeding!
  5. Type p - This will show the current partitions on the device. Again, make sure this is the correct device! You can type q and press enter if thisis the wrong device.
  6. Type o - This will clear out any partitions on the device.
  7. Type p - This will show the current partitions on the device. There should be no partitions left.
  8. Type n to add a new partition, then p for primary, then 1 for the first partition on the drive. Press enter to accept the default first sector, then type +512M for the last sector.
  9. If after you're done with the step 9 it asks about removing a signature, confirm it with y.
  10. Type t to change the partition type, then type c to change the first partition type to W95 FAT32 (LBA).
  11. Type n to add a new partition, then p for primary, then 2 for the second partition on the drive. Press enter twice to accept the default first and last sector.
  12. If after you're done with the step 12 it asks about removing a signature, confirm it with y.
  13. Type w to write the partition table and exit.
  14. Your microSD card is now partitioned.
  15. Format the partitions. Remember to use the correct device from step 4!
mkfs.vfat /dev/sda1
mkfs.ext4 /dev/sda2
  1. cd /mnt. Depending on your distro, this could be cd /mount
  2. Create the mount directories, mount the drives and change directory to the root mount:
mkdir boot root
mount /dev/sda1 boot
mount /dev/sda2 root
cd root
  1. Selected the version you want for your RaspberryPI and use wget to download it.
wget http://os.archlinuxarm.org/os/ArchLinuxARM-rpi-aarch64-latest.tar.gz
  1. Decompress the file. Use the the name of the file you downloaded in the previous step. For example, to decompress the AArch64 file, use:
tar -xvzf ArchLinuxARM-rpi-aarch64-latest.tar.gz
  1. mv boot/* ../boot
  2. sync
  3. If you decided to download AArch64 version, you need to run this command:
sed -i 's/mmcblk0/mmcblk1/g' etc/fstab
  1. cd ..
  2. umount boot root
  3. rmdir boot root

Done! You have a barebones ArchLinux install in your microSD!

Part 1.5: AArch64 Troubleshooting

Since AArch64 is quite new, there are some issues that could happen. At the time this guide was written, there's an issue that it's not possible to use the keyboard after booting. You can check the date on the bcm2711-rpi-4-b.dtb file, in the boot partition, and if it dates 18th January 2021, it's a bad file. You need to replace it with this one: https://github.com/raspberrypi/firmware/raw/master/boot/bcm2711-rpi-4-b.dtb After replacing it, everything will work as it should.

If you're running an outdated version of ArchLinux, you might need to do a full system update to solve the issue. Connect an ethernet cable, connect via ssh, login with the alarm user, su to root and proceed with the steps below to perform a full system update.

Part 2: Initial configuration

Put your microSD card in your Raspberry Pi and turn it on. It will boot to the login prompt.

The standard user login is alarm and password alarm. alarm stands for "Arch Linux ARM".

The root user login is root and password root.

Go ahead and login as root and start doing the steps below:

  1. Update your timezone: timedatectl set-timezone Europe/London. You can check the available timezones with ls /usr/share/zoneinfo and searching inside that directory. Example: ls /usr/share/zoneinfo/America will allow me to find the America/Sao_Paulo timezone.
  2. Update the clock: timedatectl set-ntp true. If you have a RTC (Real Time Clock) module, you should setup it here. I don't have one to provide the steps.
  3. nano /etc/locale.gen and remove the # from your locale (e.g. en_US.UTF-8). I was tempted to put vi here, but this guide is aimed at beginners.
  4. If this is your first time using nano, Ctrl + O saves the file and Ctrl + X exits nano.
  5. Run locale-gen.
  6. localectl set-locale LANG=en_US.UTF-8. Make sure you replace en_US.UTF-8 with the locale you uncommented in step 3.
  7. hostnamectl set-hostname <name>. Make sure you replace <name> with your desired hostname. If you're out of ideas, check this reddit link for some inspiration ;)
  8. nano /etc/hosts and make sure it has this lines, replacing myhostname with the hostname you set in the previous step:
127.0.0.1		localhost.localdomain	myhostname	localhost
::1				localhost.localdomain	myhostname	localhost
  1. (Optional) Add color to pacman output: sed -i 's/#Color/Color/' /etc/pacman.conf
  2. Setup swap memory. This will reserve 1 GiB of your SD card to use as virtual memory, and set it to an extremely low priority, so it only uses it only if your system is completely out of physical RAM memory.
fallocate -l 1024M /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile       none    swap    defaults        0       0' >> /etc/fstab
echo 'vm.swappiness=1' > /etc/sysctl.d/99-sysctl.conf

It is highly recommended that you perform a complete system update now.

Plug an ethernet cable to your Raspberry Pi before proceeding.

If you only have access to WiFi, check the next section for how to setup a temporary connection.

Make sure you have a working network and run:

  1. pacman-key --init
  2. pacman-key --populate archlinuxarm
  3. pacman -Syu
  4. This could take a few minutes, depending on how much you have to update. Go get coffee :)
  5. Once it is done, run reboot and you're ready to go!

Part 3: User setup

It is not recommended to keep using the system as root for a number of reasons. This part aims to do a basic user setup to get you started on using your system.

Part 3.1 - Enabling wheel group to run sudo

Here we will use visudo utility to edit group permissions to run administrative commands with sudo.

  1. pacman -S sudo
  2. EDITOR=nano visudo. If you know how to use vi, you can omit the EDITOR=nano part.
  3. Search for the line %wheel ALL=(ALL) ALL and uncomment it (i.e. delete the # from the start of the line.)
  4. Save and exit nano.

Part 3.2 - Creating a new user.

Now you want to create your user. In the steps below, replace your_username with your intended login username.

Still as root, run:

useradd -m -G wheel your_username

Change your password:

passwd your_username

Delete the standard user:

userdel alarm

Now you're ready! reboot and login with your user! Enjoy!

Wi-Fi Setup

karog, on ArchLinux ARM forums provided a simple way to connect to Wi-Fi. As root, do the following steps:

  1. nano /etc/systemd/network/wlan0.network to configure the wlan0 interface:
  2. Add the following contents to the file:
[Match]
Name=wlan0

[Network]
DHCP=yes
  1. wpa_passphrase "<SSID>" "<PASSWORD>" > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf. Replace and with your respective Wi-Fi network name and password.
  2. systemctl enable wpa_supplicant@wlan0 to enable the Wi-Fi when booting
  3. systemctl start wpa_supplicant@wlan0 to connect to Wi-Fi.

You're good to go!

If you ever want to remove Wi-Fi connection (e.g. when you want to make it connect only through ethernet):

  1. systemctl stop wpa_supplicant@wlan0
  2. systemctl disable wpa_supplicant@wlan0
  3. rm /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
  4. rm /etc/systemd/network/wlan0.network
@alexjowilson
Copy link

On step 14 for macOS, when I run that command, I get this returned to me, /dev/disk2s1 does not appear to be a whole disk. I was wondering if you knew any solutions to this?

@TheZoc
Copy link
Author

TheZoc commented Oct 25, 2021

@alexjowilson This is the command line written in the 14th step:

sudo diskutil partitionDisk /dev/disk2 MBR fat32 "boot" 200m UFSD_EXTFS4 "root" 0b

Notice that it uses the "whole disk" path: /dev/disk2.

From your error message, I assume you're trying to use /dev/disk2s1, which is already a partition. It's not possible to create a primary partition inside another partition. Using /dev/disk2 should do the trick!

Make sure there are no partition in the disk you're trying to create and format a partition. Steps 5-11 cover this.
Also, friendly reminder: Doing all of that will wipe the data on the target disk. Make sure you're targeting the correct disk number! 😉

@Etzyio
Copy link

Etzyio commented Nov 21, 2021

在Mac系统的第14步,当我运行该命令时,我将其返回给我,/dev/disk2s1 does not appear to be a whole disk。我想知道你是否知道任何解决方案?

I chang disk name
sudo diskutil partitionDisk /dev/disk4 MBR fat32 "BOOT" 200m UFSD_EXTFS4 "ROOT" 0b

@t-scale
Copy link

t-scale commented Dec 2, 2021

Hi,
You don't need to install a free trial of proprietary software to install arch linux ARM on RPi from a mac computer.
Paragon will mess with your macOS filesystem.
Just do it from a Linux virtual machine (via vagrant, it's dead simple) and follow the official instructions from
https://archlinuxarm.org/platforms/armv8/broadcom/raspberry-pi-4

@TheZoc
Copy link
Author

TheZoc commented Dec 2, 2021

Hi @t-scale,

I'd love if you could provide step by step on how achieve that.
I tried a few VMs to do this setup, but the lack of direct access to the hardware prevented my from getting a working sd card.

@t-scale
Copy link

t-scale commented Dec 2, 2021

hey @TheZoc ,

I'm using vagrant via the virtualbox backend on my mac to run arch linux and doing installs to sd cards for my rpi.
here's how i set that up on my mac:

  • get virtual box and vagrant with homebrew:
    brew install --cask virtualbox
    brew install --cask vagrant

  • install the arch linux image:
    mkdir archlinux && cd archlinux
    box add archlinux/archlinux
    press 2 for 2) virtualbox
    vagrant init archlinux/archlinux

  • open virtualbox, go to Machine > Settings... or just type cmd+s

  • go to the Ports tab then USB, connect your sd card adapter to your mac (with or without card inside).

  • click the usb icon with the '+' sign, select your device.

  • you can repeat those two last steps by connecting any other usb device to the same port, it'll make them recognizable by the vm.
    (bear in mind that when used by the vm, those devices won't be available by the mac system as they're essentially jailed).

  • quit virtualbox.

  • power up and ssh into your arch linux vm:
    vagrant up
    vagrant ssh

also, i recommend you to install the qemu libraries which lets you cross-compile and spawn into different architectures, including arm, from your mac/linux vm computer.

@Etzyio
Copy link

Etzyio commented Dec 4, 2021

hey ,
I used mac with m1, I can't use Linux virtual without Parallels Desktop. May it can be installed through docker.

@t-scale
Copy link

t-scale commented Dec 19, 2021

i reckon using Docker might be best, yes.
brew install docker && docker pull archlinux (or any distro you prefer)

@kiastorm
Copy link

kiastorm commented Apr 9, 2022

On Mac OS, I was getting boot does not appear to be a valid volume name for its file system after running sudo diskutil partitionDisk /dev/disk2 MBR fat32 "boot" 200m UFSD_EXTFS4 "root" 0b.

The fix is to use an uppercase name: "boot" -> "BOOT"

sudo diskutil partitionDisk /dev/disk2 MBR fat32 "BOOT" 200m UFSD_EXTFS4 "root" 0b

I also had to run sudo sed -i .bak 's/mmcblk0/mmcblk1/g' etc/fstab instead of sudo sed -i 's/mmcblk0/mmcblk1/g' etc/fstab.

@itspacchu
Copy link

There's an issue with the default kernel provided
if anyone encounters
invalid bus width while installation

if you boot into emergency mode ( ref )

pacman -S linux-rpi raspberrypi-bootloader raspberrypi-firmware

Use UUID in fstab so it doesn't wait forever for sdcard

@TheZoc
Copy link
Author

TheZoc commented May 25, 2022

Thanks for the update everyone, those are indeed necessary in the latest version!

@Yayantaff
Copy link

Yayantaff commented May 31, 2022

@TheZoc,
cd /Volumes/root
at step 14. Also, what is this supposed to mean : The 'root' is allocated 0b? Where could I refer to what is going on here ?
It throws me this error :
-bash: cd: /Volumes/root: No such file or directory
Pls refer to the last line. Could you guide me here ?

Screen Shot 2022-05-31 at 7 01 25 PM

@zekromisblack
Copy link

this does not work if you have a compute module 4 as its missing critical files for it to boot

@Animesh-Thakur
Copy link

I got this to work on WSL, requires recompiling the wsl kernel, this video goes into detail https://www.youtube.com/watch?v=iyBfQXmyH4o .

@danie1kr
Copy link

Apparently, it is hostnamectl hostname <name> for setting the fresh install host name.

@shinmorisawa
Copy link

nice. keep up the good work!

@plutobox
Copy link

Getting an error when running pacman -Syu on armv7h installation. Invalid option �. Tried different locale sets with no luck.

...
:: Proceed with installation? [Y/n] Y
(115/115) checking keys in keyring                                                                                                                [#########################################################################################] 100%
(115/115) checking package integrity                                                                                                              [#########################################################################################] 100%
(115/115) loading package files                                                                                                                   [#########################################################################################] 100%
(115/115) checking for file conflicts                                                                                                             [#########################################################################################] 100%
(115/115) checking available disk space                                                                                                           [#########################################################################################] 100%
error: hook /usr/share/libalpm/hooks/._glib-compile-schemas.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._30-systemd-udev-reload.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._30-systemd-tmpfiles.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._20-systemd-sysusers.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._30-systemd-binfmt.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._60-depmod.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._60-mkinitcpio-remove.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._30-systemd-update.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._90-mkinitcpio-install.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._90-linux-rpi.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._60-linux-rpi.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._30-systemd-sysctl.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._30-systemd-catalog.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._30-systemd-daemon-reload.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._gio-querymodules.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._40-update-ca-trust.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._dbus-reload.hook line 2: invalid option �
error: hook /usr/share/libalpm/hooks/._30-systemd-hwdb.hook line 2: invalid option �
error: failed to commit transaction (failed to run transaction hooks)
Errors occurred, no packages were upgraded.
[root@alarmpi ~]#

@gorgbus
Copy link

gorgbus commented Apr 18, 2024

everytime I do the complete system update after fresh install it bricks the install and after reboot I get rainbow screen and cant do anything

@TheZoc
Copy link
Author

TheZoc commented Apr 23, 2024

It might be possible that the latest version of armv7h is broken. I'm currently using aarch64 and it's working nicely :)

@gorgbus
Copy link

gorgbus commented Apr 24, 2024

It might be possible that the latest version of armv7h is broken. I'm currently using aarch64 and it's working nicely :)

I am using the aarch64, however I fixed in the meantime by switching to linux-rpi kernel

@TheZoc
Copy link
Author

TheZoc commented May 3, 2024

For anyone following this guide in the future, increase your boot partition size to 512Mb.
My rpi4 that I setup in 2021 is struggling with initramfs sizes :(

Edit: Updated the guide with the increased value

@emzxcv
Copy link

emzxcv commented Jul 22, 2024

For anyone in 2024, running a mac Ventura 13.5.2 (22G91)

sudo sed -i 's/mmcblk0/mmcblk1/g' etc/fstab 
sed: 1: "etc/fstab": invalid command code e

This kept erroring for me and i changed it to :
sudo sed 's/mmcblk0/mmcblk1/g' etc/fstab > etc/fstab.tmp && mv etc/fstab.tmp etc/fstab

Check it worked:
grep mmcblk1 etc/fstab

@emzxcv
Copy link

emzxcv commented Jul 22, 2024

I still can't seem to get it working...
I am getting an error like PARTUUID="" not found.

etc/fstab looks like this and i used the aarch64.

# <file system> <dir> <type> <options> <dump> <pass>
/dev/mmcblk1p1  /boot   vfat    defaults        0       0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment