I have provided a rough guide below, this is taken from my notes from going through this process on macOS Sonoma a little while back, I’m not aware of any changes to newer versions that would require additional steps, but if you do encounter any problems note down the exact error message(s) and let me know.
I have assumed that you have little to no knowledge/experience of working within the Terminal so apologies in advance if this is not the case.
The quick overview of the steps are…
- Install Homebrew package manager (which will install
Command Line Tools for Xcode as part of it process)
- Install
uuu
- Download the
librem5-flash-image script
- Install the
librem5-flash-image script Python module dependencies
- (Optionally) Install
librem5-flash-image script
- Go flash
There are some additional minor operations throughout the process (creating directories etc,.) but I think it’s reasonably straightforward. Everything will be done from the command line within a Terminal window so open the Terminal application from either Finder → Applications → Utilities → Terminal or Launchpad → Other → Terminal
First, Install Homebrew, the install process will make a number of checks including whether or not sudo is available so you may be prompted to enter your user password. The installer will then present the details of everything it will be doing and will wait for you to confirm by pressing enter. From the terminal, enter the follwoing install command…
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Hopefully the install completes without errors, note the last few lines of output, it is likely to ask you to enter a few lines of code into the terminal, the lines add the package manager to the terminal environment and are required, the lines are likely to start with echo or eval, each line should be entered separately.
Optionally turn off Homebrew’s analytics by entering brew analytics off
Next, install uuu
brew install uuu
Next, create and change into a direcotry where the librem5-flash-image script will be downloaded and stored.
mkdir -p ~/.tools/librem5
cd ~/.tools/librem5
Next, download the librem5-flash-image script code repository
git clone --depth 1 https://source.puri.sm/Librem5/librem5-flash-image.git
Next, change into the script repository directory and install the librem5-flash-image script dependencies (Python modules). You will see some warning messages (one for each module being installed) regarding the modules being installed in a location outside of your PATH, these can be safely ignored, you may also see a notice about an newer version of pip being available, this can also be safely ignored.
cd librem5-flash-image
pip3 install -r requirements.txt
Optionally, install the librem5-flash-image script, this is not an absolute requirement but by installing/linking the script to a location in your PATH (/usr/local/bin is in the PATH by default) you can envoke the script without having to specify the path to the script or as most do, be in the same directory as the script. Using sudo here, you may be prompted for your user password.
sudo install -m 755 -d /usr/local/bin
sudo ln -s $(pwd)/scripts/librem5-flash-image /usr/local/bin/librem5-flash-image
exec zsh
Everything you have done so far installs and sets up all the tools/utilities required to flash the Librem 5 from within macOS, the set up is now done, the above steps do not need to be repeated for subsequent flashing operations.
You are now ready to flash, as mentioned earlier in the thread, I do this as a two step process, I first download the files using librem5-flash-image then I flash the Librem 5 using uuu directly. This is due to uuu requiring to be envoked with elevated privileges so to download and flash in a single operation requires envoking librem5-flash-image with sudo and I prefer to limit my use of sudo to the minimum.
You have some options (you should refer to official documentation for all options) when it comes to which image you flash to the Librem 5, you can choose an encrypted image (LUKS) or plain by adding --variant LUKS or --variant plain respectively you can choose to install the current testing/alpah release (crimson) by adding --dist crimson omitting the --dist argument will cuase the script to choose the latest build of the current release (byzantium), you can add --stable to choose the current stable build of the current release. I am choosing to use the encrypted (LUKS) variant of the testing build (crimson) here
librem5-flash-image --dir ~/Downloads/Librem5/images/crimson/alpha --skip-flash --skip-cleanup --variant luks --dist crimson
Next, change into the directory where the files have been downloaded and flash the Librem 5 with uuu, you can choose to put the Librem 5 into download mode either before or after envoking uuu it doesn’t matter (refer to the Reflashing guide you linked to previously for instructions to set the Librem 5 into download mode). Note that during the flashing process the Librem 5 changes it’s USB device identity so your machine may ask you if you want to allow access to device twice, the phone should reboot once the flashing process completes. Before envoking uuu I would resize the terminal window, at least increase it’s width, it not absolutely required, however, the current release version of uuu has an issue which will result in it throwing an exception when run in a terminal of default width (80 characters), it doesn’t affect the flashing process but does throw a notice error and ends up producing a lot of output which, if you’re not expecting it, can be a little disturbing.
cd ~/Downloads/Librem5/images/crimson/alpha
sudo uuu flash_librem5r4.lst
The Librem 5 should now be flashed with it’s new image, you can choose to keep the downloaded images files or remove them, if removing them, change out of the directory and remove it
cd ~
rm -rf ~/Downloads/Librem5