¶ Introduction
We sometimes encounter the situation where users with limited or no Internet connectivity need to update Endless OS, install an application, or update an application.
Endless provides the ability to copy over OS updates as well as Flatpak applications from one computer to another using a USB drive. This functionality has some rough edges, so these instructions describe the known issues and workarounds for them, as well as best practices to maximise your chance of success.
¶ Preparation
First, find a USB drive to use.
¶ Capacity
You will need a drive with enough free space for the apps and their dependencies—likely at least 8 GB. Delete files on the drive as needed to free up space.
¶ USB 3
If possible, you should use a USB 3.0+ drive, which can usually be distinguished from slower USB 2.0 drives by the blue color of the connector when viewed on the side that plugs into the computer.
You should also use a USB 3.0+ port if your computer has one. These can usually be identified by an "SS" USB logo or a blue color.
¶ Filesystem
For best performance, ensure that the drive uses either the ext4 filesystem or, on Endless OS 4.0 or newer, the exFAT filesystem. You can check your Endless OS version in the Settings app on the "About" page. You can check the filesystem used on a USB drive using the "Disks" application: click on the disk in the column on the left and then check the value labeled "Contents". If it says "FAT", you can reformat it by following these steps.
The following steps will permanently delete everything on the USB drive!
- Copy any data you want to keep off the drive. All data on the drive will be deleted by following these steps.
- In the Files app, right click on the removable drive in the left column and choose "Format..."
- In the dialog, enter a volume name such as "updates" and choose the type "Internal disk for use with Linux systems only (Ext4)". Click "Next", then "Format", and wait for the operation to complete. Then click the triangular "Play" button to mount the filesystem.
¶ Drive label on EOS 3.9.4 or older
Due to a bug in Endless OS versions older than 3.9.4, you need to ensure the USB drive has a label, unless you are using 3.9.4 or newer on both the source and target machines. An unlabeled drive will show up in the Disks app as "Filesystem" under the "Volumes" header:
If this is the case for you, click on the Gear icon, select "Edit Filesystem...", enter a label such as "updates", and click the "Change" button.
¶ Copying apps to the USB drive
Plug the USB drive into the computer and open the App Center. You should see a "USB" category appear at the bottom-left side of the app, below the other categories. If it does not appear, ensure that the usb disk is plugged in correctly and properly formatted, as described above.
To copy an app to the USB drive, search for it in the App Center, and click on it to open its details page. If the application is not yet installed, install it. Then, if it is compatible with USB updates, you should see a "Copy to USB" button on its details page.
Not all apps are compatible with this feature. If the Copy to USB button does not appear, try a different app.
Click on the "Copy to USB" button, and wait until the progress spinner goes away before safely ejecting the disk using the Documents application. The process can be repeated with as many apps as can fit on the disk. At this stage the apps are ready to be installed on a different computer.
For large apps, this process can take a long time. Please be patient! We hope to improve the progress indicator in a future version.
For information on how to use the command line (the "Terminal" application) instead of the App Center to copy the app to the USB drive, see https://docs.flatpak.org/en/latest/usb-drives.html
¶ Copying OS updates to the USB drive
If possible, update Endless OS using the App Center before following these steps.
- Plug the USB drive into the computer and open the App Center.
- You should see a USB icon on the bottom left side of the page. If this icon isn't available, ensure that the USB disk is plugged in correctly and properly formatted (see above).
- Click on the USB icon. You should see a "Copy OS to USB" button at the top of the page.
Click "Copy OS to USB" and wait for the progress spinner to stop.
Please be patient – this may take tens of minutes.
Once the OS is copied to the USB drive, there are a few additional steps needed to work around known issues:
- In the Files application, select the USB drive from the column on the left. In the file listing on the right, right click in the empty space and choose "Open in Terminal":
- Copy the following commands, and paste them into the Terminal window that appears:
# Work around the openh264 extension incorrectly being copied to USB; can be
# skipped on Endless OS 3.9.4 or newer.
rm -f .ostree/repo/refs/mirrors/org.flathub.Stable/runtime/org.freedesktop.Platform.openh264/x86_64/* && \
ostree --repo=.ostree/repo summary --update
# Work around a bug when updating a machine running Endless OS 3.8.x or older.
ostree create-usb . com.endlessm.Apps ostree-metadata
# Work around a bug when updating a machine running Endless OS 3.8.x or older.
# This command requires Internet access, but can be skipped if the computer
# that will receive the OS update is on Endless OS 3.9.0 or later.
flatpak install -y --system flathub org.gnome.Totem.Codecs && \
flatpak create-usb . org.gnome.Totem.Codecs
# Work around a bug when installed languages differ between source and target machine.
# See troubleshooting section below.
# This command requires internet access, but can be skipped in some circumstances.
# If you receive error messages mentioning "Locale" and "No such file or directory",
# this workaround or one like it is needed.
flatpak install --reinstall -y --system flathub org.gnome.Platform.Locale//41 && \
flatpak create-usb . org.gnome.Platform.Locale//41
- Press
Enterand wait a few seconds for the commands to complete and the Terminal to return to a$prompt. - Safely eject the drive using the Files application and unplug it from your computer.
¶ Advanced method
If you are a technically-adept user, you may use the following Terminal command as an alternative to step 3 above, replacing the path at the end with the actual path to the USB mount:
pkexec /usr/bin/eos-updater-prepare-volume /path/to/usb
This offers marginally more information while the process is running.
¶ Using the USB drive for offline updates
Once you've copied apps and/or OS updates to a USB drive as detailed above, it can be used to update an offline machine.
¶ Installing apps from a USB drive
- Insert the USB drive containing the app you want to install. The App Center should open automatically.
- You should see a USB icon on the bottom left side of the page. If this icon isn't available, ensure that the USB disk is plugged in correctly.
- Clicking on the USB icon should provide a list of apps available on the drive.
- You can then click on a desired app and install it using the "Install" button.
¶ Updating apps from a USB drive
- Insert the USB drive containing the app you want to update. The App Center should open automatically.
- You should see a USB icon on the bottom left side of the page. If this icon isn't available, ensure that the USB disk is plugged in correctly.
- Click on the "Updates" tab and wait for app updates to appear. Click "Update All" to apply all updates or use the individual "Update" buttons.
¶ Updating the OS from a USB drive
- Insert the USB drive containing the OS update you want to apply. The App Center should open automatically.
- You should see a USB icon on the bottom left side of the page. If this icon isn't available, ensure that the USB disk is plugged in correctly.
- Click on the "Updates" tab and wait for the OS update to appear. Click "Download" to apply the OS update and wait for the operation to complete. Reboot your computer to finish applying the OS update.
¶ Advanced: Manually updating the OS
The following steps are only as a last resort if the normal process fails.
If the automatic OS update process above fails, it may be possible to update the OS from the Terminal. However, this will not install any Flatpak applications that are required by the new OS version (which are not otherwise present in the new OS version).
sudo ostree find-remotes --finders=mount --pull com.endlessm.Os os/eos/amd64/eos3a
sudo ostree admin deploy eos:os/eos/amd64/eos3a
The following apps may be missing after you upgrade the OS using this method, but you should be able to install them by leaving the USB device plugged in, then checking the "USB" tab in the App Center when running the new version of the OS:
- Videos
- Chromium web browser
- Rhythmbox
- Cheese
¶ Troubleshooting
¶ “No such file or directory” for Locale runtimes
In some scenarios, OS upgrades may fail with an error like the following:
Unable to upgrade to Endless OS 4.0.2:
While pulling runtime/org.gnome.Platform.Locale/x86_64/41 from remote flathub:
Importing long hexadecimal string.dirtree:
fstatat(long hexadecimal string.dirtree):
No such file or directory
This is caused by the installed languages being different between the computer that copied updates to the USB stick, and the computer installing them. You may see this issue with different .Locale runtimes.
To work around this issue, see the final step of the "Copying OS updates to the USB drive" section above.
¶ Updating OS to EOS4 does not work
If you are trying to update the OS to EOS4 from a version older than 3.9.5, the upgrade will not happen.
In order to make a succesful update:
You will initially need to update to a version newer than 3.9.5 but not 4.0, and then you will need to update to Endless 4.0.x
You can have both updates in the same USB, you'll just need to follow the process twice, one for each checkpoint necessary.
Once you have both versions in the USB, try updating the OS. The first time, the system will be updated to the oldest chosen checkpoint (eg. v3.9.6).
After that update is done, you should insert the USB again and it will finally update the OS to v4.0.x