The Installation Guide

The intention of this reference Guide is to assist users in the process of installing Hyperbola GNU/Linux-libre from the live system booted with the official installation image. This page assumes you have some level of experience with GNU/Linux systems and utilities, especially with the command line. Before beginning, we recommend you to employ the man command to read the man page of any command they are not familiar with. The Hyperbola wiki (known as HyperWiki) should be the primary source of information and your first resource during trouble-shooting.

Blind and visually impaired users

Hyperbola includes brltty, for those who own braille displays. The brltty package available was compiled with as few dependencies as possible. If you wish to use braille, you will need to supply the brltty parameter at the boot prompt. Alternatively, you can start brltty from the shell, after the system has booted.

The brltty boot-time parameter consists of three comma-separated fields: driver, device, and table. The first is the driver for your display, the second is the name of the device file, and the third is a relative path to a translation table. You can use “auto” to specify that the driver should be automatically detected. We encourage you to read the brltty documentation for a fuller explanation of the program.

Once brltty is running, you may wish to disable speech. You can do so via the “print screen” key, also known as sysrq.

Create bootable image

Download live image

Make sure to change your BIOS settings so that your computer will boot from your optical disk or USB stick.

Download the new Hyperbola ISO from the download page.

  • Instead of six different images we only provide a single one which can be booted into an i686 and x86_64 live system to install Hyperbola GNU/Linux-libre over the network.

Verify the live image

Once you have downloaded the Live image as described you should verify it following:

This page explains how to verify their integrity and authenticity.
  1. Create a directory called live_image in your home directory.
  2. Move the live image you downloaded in this directory.
  3. Download the following files and move them into the live_image directory.
Hyperbola live image

File Description
hyperbola-milky-way-v0.4.4-dual.iso.sha512 Contains the SHA512 sums to check the integrity of the Hyperbola live image.
hyperbola-milky-way-v0.4.4-dual.iso.sha512.sig Signed by the Hyperbola team to check the authenticity of the sha512sum file of the Hyperbola live image.

Your live_image directory should now contain 3 files: Your live image and the sha512 file and the signed one, like this:

  • hyperbola-milky-way-v0.4.4-dual.iso
  • hyperbola-milky-way-v0.4.4-dual.iso.sha512
  • hyperbola-milky-way-v0.4.4-dual.iso.sha512.sig
Integrity check

To verify the integrity of your live image, generate its SHA512 sum and compare it to the one found in the sha512sum file.

In most GNU/Linux distributions the SHA512 sum can be generated by opening a terminal and running the following commands:

cd live_image
sha512sum -b *.iso

The last command should show you the SHA512 sum of your live file. Compare it to the sha512sum file. If it match, you've successfully verified the integrity of your live image.

If you have coreutils version 8.25 or newer, another way of checking the sum is to ask the sha512sum command to check the file against the sha512sum file, like this:
sha512sum -c hyperbola-milky-way-v0.4.4-dual.iso.sha512
Authenticity check

To verify the authenticity of the sha512sum file, we need to check the signature on the signed file.

Import the Hyperbola signing key:

gpg --keyserver --recv-key "C92B AA71 3B8D 53D3 CAE6 3FC9 E697 4752 F970 4456"
If gpg complains about the key ID, try the following commands instead:
gpg --keyserver --recv-key F9704456
gpg --list-key --with-fingerprint F9704456

Check the output of the last command, to make sure the fingerprint is C92B AA71 3B8D 53D3 CAE6 3FC9 E697 4752 F970 4456.

Verify the authenticity of the sha512sum file, like this:

cd live_image
gpg --verify hyperbola-milky-way-v0.4.4-dual.iso.sha512.sig

The output of the last command should tell you that the file signature is 'good' and that it was signed with the following key: F9704456.


This wiki article is based on Mint's download page. We may have removed non-FSDG bits from it.

2017/09/27 01:49


  • Install images are signed and it is highly recommend to verify their signature before use. On Hyperbola, this can be done by using pacman-key -v <iso-file>.sig
  • The image can be burned to a CD, mounted as an ISO file, or directly written to a USB stick using a utility like dd. It is intended for new installations only; an existing Hyperbola GNU/Linux-libre system can always be updated with pacman -Syu.

Writing a Hyperbola ISO image to an USB drive

Burn the image to your optical disk

To create a disk to use as your install medium, insert a blank or re-writable disk, CD or DVD, into your disk drive. Next, you will need to mount the disk.

# mount sr0

Provided your computer has a disk drive. Sr0 should the first or only, if you only have one disk drive, mount point of disk drives. You will need to address the correct destination for the command to work.

# dd if=~/hyperbola-milky-way-v0.4.3-dual.iso of=/dev/sr0 bs=2048 conv=noerror && sync

Write the image to your USB

If you don’t have an ISO writer, go (change directory) to the folder where you saved the downloaded Live image (probably the Downloads folder) and type the following into your terminal:

# dd if=hyperbola-milky-way-v0.4.3-dual.iso of=/dev/sdb bs=2048 && sync
Usually works fine, even though I’ve seen other commands; feel free to modify it.

To find out what’s the name of the USB device, type fdisk -l

You’ll probably see something like this:

Device             Boot    Start                  End              Sectors               Size        Id    Type
/dev/sda1                    2048                   8390655       8388608              4G           82    Linux swap /Solaris
/dev/sda2       *          8390656             976773167  968382512          461,8G   83    Linux
Device             Boot    Start                 End              Sectors                Size        Id    Type
/dev/sdb1       *           0                         1255423      1255424               613M      0     Empty
/dev/sdb2                     172                    63659           63488                   31M        ef    EFI (FAT-12/16/32)

From the above, sda is your HDD, and the sdb is your USB device where you’re going to write your Live image.

Also take a note of your partitions, you will come to need it when you’re creating the file system and mounting the root partition during the installation.

Once you’ve downloaded, verified and written the Live image to your USB device, you can move on to boot your computer from your USB.

# dd if=''[iso file]'' of=''[usb device file]'' bs=1M && sync
[iso file] is the path to the ISO image file.
[usb device file] is the path to the USB device file. dmesg or lsblk –fs can be used to learn this path. It is often similar to device filenames of storage devices like hard drives and SSDs, e.g. /dev/sdb 'It is very important to use the correct value' to avoid overwriting other storage devices.

Internet Connection

Connect to the Internet

As of v197, udev no longer assigns network interface names according to the wlanX and ethX naming scheme. If you are coming from a different distribution or are reinstalling Hyperbola and not aware of the new interface naming style, please do not assume that your wireless interface is named wlan0, or that your wired interface is named eth0. You can use the command ip link to discover the names of your interfaces.

A DHCP service is already enabled for all available devices. If you need to setup a static IP or use management tools, we will address this point later on.

The dhcpcd network daemon starts automatically during boot and it will attempt to start a wired connection. Try to ping a server to see if a connection was established. For example,

# ping -c 3
PING ( 56(84) bytes of data.
64 bytes from ( icmp_seq=1 ttl=47 time=183 ms
64 bytes from ( icmp_seq=2 ttl=47 time=168 ms
64 bytes from ( icmp_seq=3 ttl=47 time=183 ms
--- ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2002ms
rtt min/avg/max/mdev = 168.131/178.357/183.914/7.248 ms

If you get a ping: unknown host error, first check if there is an issue with your cable or wireless signal strength. If not, you will need to set up the network manually, as explained below.


Follow this procedure if you need to set up a wired connection via a static IP address.

First, disable the dhcpcd service which was started automatically at boot:

# rc-service dhcpcd stop

Identify the name of your ethernet interface.

# ip link
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp2s0f0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT qlen 1000
    link/ether 00:11:25:31:69:20 brd ff:ff:ff:ff:ff:ff
3: wlp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DORMANT qlen 1000
    link/ether 01:02:03:04:05:06 brd ff:ff:ff:ff:ff:ff

In this example, the ethernet interface is enp2s0f0. If you are unsure, your ethernet interface is likely to start with the letter “e”, and unlikely to be “lo” or start with the letter “w”. You can also use iwconfig and see which interfaces are not wireless:

# iwconfig
enp2s0f0  no wireless extensions.
wlp3s0    IEEE 802.11bgn  ESSID:"NETGEAR97"
          Mode:Managed  Frequency:2.427 GHz  Access Point: 2C:B0:5D:9C:72:BF
          Bit Rate=65 Mb/s   Tx-Power=16 dBm
          Retry  long limit:7   RTS thr:off   Fragment thr:off
          Power Management:on
          Link Quality=61/70  Signal level=-49 dBm
          Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
          Tx excessive retries:0  Invalid misc:430   Missed beacon:0
lo        no wireless extensions.

In this example, neither enp2s0f0 nor the loopback device have wireless extensions, meaning enp2s0f0 is our ethernet interface.

You also need to know these settings:

  • Static IP address.
  • Subnet mask.
  • Gateway's IP address.
  • Name servers' (DNS) IP addresses.
  • Domain name (unless you are on a local LAN, in which case you can make it up).

Activate the connected ethernet interface (e.g. enp2s0f0):

# ip link set enp2s0f0 up

Add the address:

# ip addr add ip_address/subnetmask dev interface_name

For example:

# ip addr add dev enp2s0f0

For more options, run man ip.

Add your gateway like this, substituting your own gateway's IP address:

# ip route add default via ip_address

For example:

# ip route add default via

Edit resolv.conf, substituting your name servers' IP addresses and your local domain name:

# nano /etc/resolv.conf
nameserver 61.95.849.8
Currently, you may include a maximum of three nameserver lines. In order to overcome this limitation, you can use a locally caching nameserver like Dnsmasq.

You should now have a working network connection.


Follow this procedure if you need wireless connectivity (Wi-Fi) during the installation process.

First, identify the name of your wireless interface.

# iw dev
        Interface wlp3s0
                ifindex 3
                wdev 0x1
                addr 00:21:6a:5e:52:bc
                type managed

In this example, wlp3s0 is the available wireless interface. If you are unsure, your wireless interface is likely to start with the letter “w”, and unlikely to be “lo” or start with the letter “e”.

If you do not see output similar to this, then your wireless driver has not been loaded.

Bring the interface up with:

# ip link set wlp3s0 up
If you get this error message:
SIOCSIFFLAGS: No such file or directory

Then, your wireless chipset could need a non-free firmware to function. This is not supported on Hyperbola.

Next, use iw dev wlp3s0 scan | grep SSID to scan for available networks, then connect to a network with:

# wpa_supplicant -B -i wlp3s0 -c <(wpa_passphrase "ssid" "psk")

You need to replace ssid with the name of your network (e.g. “Linksys etc…”) and psk with your wireless password, leaving the quotes around the network name and password.

Finally, you have to give your interface an IP address. This can be set manually or using the dhcp:

# dhcpcd wlp3s0

If that does not work, issue the following commands:

# echo 'ctrl_interface=DIR=/run/wpa_supplicant' > /etc/wpa_supplicant.conf
# wpa_passphrase <ssid> <passphrase> >> /etc/wpa_supplicant.conf
# ip link set <interface> up # May not be needed as dhcpcd should bring it up but may be needed for wpa_supplicant.
# wpa_supplicant -B -D nl80211 -c /foobar.conf -i <interface name>
# dhcpcd -A <interface name>


Follow this procedure if you need ADSL with PPPoE/PPPoA during the installation process.

First, identify the name of your ethernet interface.

# ip link
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp2s0f0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT qlen 1000
    link/ether 00:11:25:31:69:20 brd ff:ff:ff:ff:ff:ff
3: wlp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DORMANT qlen 1000
    link/ether 01:02:03:04:05:06 brd ff:ff:ff:ff:ff:ff

In this example, the ethernet interface is enp2s0f0.

Second, create the PPP net script and the net script for the ethernet interface to be used by PPP:

# ln -s /etc/init.d/net.lo /etc/init.d/net.ppp0
# ln -s /etc/init.d/net.lo /etc/init.d/net.enp2s0f0
Be sure to set rc_depend_strict to YES in /etc/rc.conf.

Now we need to configure /etc/conf.d/net.

# nano /etc/conf.d/net

config_eth0=null (Specify the ethernet interface)
link_ppp0="enp2s0f0" (Specify the ethernet interface)
holdoff 3
child-timeout 60
lcp-echo-interval 15
lcp-echo-failure 3
noaccomp noccp nobsdcomp nodeflate nopcomp novj novjccomp"
It is also possible to set the password in /etc/ppp/pap-secrets.
Please carefully read the section on ADSL and PPP in /usr/share/doc/netifrc-*/net.example.bz2. It contains many more detailed explanations of all the settings any particular PPP setup will likely need.

Now that the interface is configured, we can start it using the following commands:

rc-service net.ppp0 start

Behind a proxy server

If you are behind a proxy server, you will need to export the http_proxy and ftp_proxy environment variables.


Partition disks

These instructions assume that you are using MBR (Master Boot Record) as the partitioning scheme for your installation disk. Installation on a GPT-based disk is slightly different than the process described here.

Once your computer has successfully booted into the Live USB device, type the following into you terminal:

# cfdisk /dev/sda

This will bring up a graphical partitioning table, and will look somewhat like fig. 1 (see above). Use the Tab and arrow keys to navigate. This is assuming that you want Hyperbola installed on your HDD.

Delete all the partitions so that you only see Free Space.

Then make a new partition by choosing New and then make it Primary. Make this first partition a Swap. 1/4 of you computer’s memory should be enough. So with 8 GB of memory, your Swap would then be 2 GB. Then choose the End flag.

The rest of the space should be made Primary, then choose the Boot flag to make this partition bootable. Then choose Write and type ’yes’ to save your changes to disk. Then Quit.

You will then have something like this:

sda2 Boot  Primary  Linux
sda1             Primary  Linux  Swap / Solaris

Take note of the fact that the root partition that you soon will mount, is the bootable one (in this example the sda2) that you made from the rest of the space after creating the Swap partition.

Remember to create any stacked block devices like LUKS, or RAID.

System Configuration

Activate swap

# mkswap /dev/sda1
# swapon /dev/sda1

Keyboard layout

For many countries and keyboard types appropriate keymaps are available already, and a command like loadkeys uk might do what you want. More available keymap files can be found in /usr/share/kbd/keymaps/ (you can omit the keymap path and file extension when using loadkeys).

If you’re not using an English keyboard, you can set your language by typing loadkeys followed by you language. Available keymap files can be found in /usr/share/kbd/keymaps/ (you can omit the keymap path and file extension when using loadkeys). For British users, type:

# loadkeys uk.

Format the partitions

If you are using (U)EFI you will most probably need another partition to host the UEFI System partition.

Create a file system

To create the ext4 file system, type:

# mkfs.ext4 /dev/sda2

Mount the partitions

We now must mount the root partition on /mnt. You should also create directories for and mount any other partitions (/mnt/boot, /mnt/home, …) and mount your swap-partition if you want them to be detected by genfstab.

Mount the root partition

# mount /dev/sda2 /mnt

Verification of system-date

To check that your computer has the correct time, enter date in the terminal.

# date

If the date is incorrect, you will need to manually set the correct time.

# date MMDDhhmm[[CC]YY][.ss]

where MM is the month, DD the day, hh the hour, mm the minutes, CC the century, YY the year and .SS the seconds of current time, the seconds can be omitted (and then also the dot before them should be omitted), the year can also be submitted or just the century. for instance if the current time is 32 seconds and 44 minutes past 18 (6 pm) on the 13th November 2013. Then the command would be:

# date 111318442013.32

Base system installation

Before installing, you may want to edit /etc/pacman.d/mirrorlist such that your preferred mirror is first. This copy of the mirrorlist will be installed on your new system by pacstrap as well, so it's worth getting it right.

Install the base system using pacstrap:

# pacstrap /mnt base

You can install additional packages passing base and the names of these packages as arguments after the root directory of the new installation (all packages from the base group are installed if no package is specified).

You can also use package group base-devel to include developement and contribution tools
If you have a btrfs root, you probably want to install also btrfs-progs.

Wireless tools installation

If your wireless network is WPA protected, you'll need wpa_supplicant to connect to it:

# pacstrap /mnt wpa_supplicant

System configuration

Generate an fstab

# genfstab -U -p /mnt >> /mnt/etc/fstab

Generate a fstab with the following command (if you prefer to use UUIDs or labels, add the -U or -L option, respectively):

# genfstab -p /mnt >> /mnt/etc/fstab

Chroot and configure the base system

Next we need to enter directly our newly installed system:

# arch-chroot /mnt


Usually it’s sufficient to set your hostname to localhost.

# echo localhost > /etc/hostname

Add the same hostname, i.e. localhost, to /etc/hosts.


# nano /etc/hosts
# <ip-address> <> <hostname>                localhost.localdomain     localhost localhost
::1                             localhost.localdomain     localhost localhost


Type the following to set locale preferences in /etc/locale.conf

# nano /etc/locale.gen

Now choose your locale from what language you’re using. All locales are commented out (preceded by #) by default. Uncomment (remove the #) for your choice of locale. For US English, it should look like this:

#en_SG ISO-8859-1
en_US.UTF-8 UTF-8
#en_US ISO-8859-1

After you’ve uncommented your language, run the command:

# locale-gen

Then check the file /etc/locale.conf. If not existing you can create it like following up:

# echo LANG=en_US.UTF-8 > /etc/locale.conf 

Then export your chosen locale, just in case for your current session

# export LANG=en_US.UTF-8

Add console keymap and font preferences in /etc/conf.d/keymaps


As the locale, you need to setup the keymap in the file /etc/conf.d/keymaps:


If you have an advanced usage of your keymap, you can watch the other functionalities, documented in the comments. You can find all the available keymaps in /usr/share/kbd/keymaps. Then run:

# rc-update add keymaps default
This only applies for CLI, is you are using X11, this won't affect your graphical environment.

Time zone

Create a symbolic link /etc/localtime to your subzone file /usr/share/zoneinfo/Zone/SubZone:

# ln -s /usr/share/zoneinfo/Zone/SubZone /etc/localtime


# ln -s /usr/share/zoneinfo/Europe/Oslo /etc/localtime

If you get ln: failed to create symbolic link ’/etc/localtime’: File exists, then run:

# ln -s -f /usr/share/zoneinfo/Zone/SubZone /etc/localtime

Hardware clock

Set the hardware clock to UTC

# hwclock --systohc --utc

Root password

Remember when you’re typing in your root password (as any password) into the terminal, it won’t show. Just carefully type in your chosen root password and repeat it when asked to.

# passwd

* Set a root password with passwd

  • Add your user to the relevant group such as:
# gpasswd -a <username> video

Bootloader installation and configuration


Finally follow these steps:

# pacman -S grub
# grub-install --target=i386-pc --recheck /dev/sdX
Here do NOT append a partition number, i.e. /dev/sdaX)

To configure the bootloader, you have to install it and generate the file grub.cfg:

# grub-mkconfig -o /boot/grub/grub.cfg


Syslinux is a collection of boot loaders capable of booting from drives, CDs, and over the network via PXE. Install the syslinux-package with the following command:

# pacstrap /mnt syslinux

For further details refer to the corresponding article at Parabola.

Create RAM-disk

Configure /etc/mkinitcpio.conf as needed (see man-page for mkinitcpio) and create an initial RAM disk with:

# mkinitcpio -p linux-libre-lts
linux-libre-lts is our default kernel since we are a long-term support distro.

If you want to install GRUB for the (U)EFI mode, you will need to make sure that:

  • The computer booted in (U)EFI mode (if /sys/firmware/efi exist, then it booted in (U)EFI mode)
  • The efivars module is loaded. (modprobe efivars will load it)

Unmount and reboot

If you are still in the chroot environment type exit or press Ctrl+D in order to exit.

# exit

Earlier we mounted the partitions under /mnt. In this step we will unmount them:

# umount -R /mnt
If you have made separate partitions on your system, do this instead:
# umount /mnt/{boot,home,}

Now reboot and then login into the new system.

# reboot

Remember to remove your installation medium (your USB stick) before you reboot into your system. To log in, you type root and your password.

Congratulations! You have now installed Hyperbola GNU/Linux-libre onto you computer.


You will now have to create a user and get user privileges like doas. And of course, you will have to install your additional environment for working.

Configure pacman

Edit /etc/pacman.conf and configure pacman's options, also enabling the repositories you need.

Update the system

At this point you should update your system.

# pacman -Syu

Add an user and groups for privileges

Finally, add a normal user.

# useradd -g users -m -s /bin/bash <username>

You should consider the following groups to be used at start:

# usermod -aG video <username>
# usermod -aG audio <username>
# usermod -aG sys <username>
# usermod -aG storage <username>
# usermod -aG optical <username>
# usermod -aG power <username>
# usermod -aG network <username>
# usermod -aG input <username>

If you want to access for updating:

# usermod -aG wheel <username>

Please remember also that to execute and access installed free, libre games you need another group-membership:

# usermod -aG games <username>

Service management

Since Hyperbola is oriented on init-freedom, we suggest you read about OpenRC which is our main default init system.

Graphical environment and your favorite desktop

Hyperbola does not include the common known desktop-environments, for example Gnome, KDE, Xfce, Mate, Cinnamon, Budgie, LxDE or LxQT. If you want to know about our reasoning doing so, please read here more about.

You can for sure create your own working graphical environment as we offer several window managers and Lumina Desktop as working desktop-environment.

Final note about included packages, applications and others

We ask to make usage of the package-search so you can look out to find packages for your further installation, for example graphical file-managers and more. Hyperbola has not the goal to offer a wide number of packages as we focus on minimalism so far. So we do not have the interest to include more packages!


Your new Hyperbola GNU/Linux-libre base system is now a functional GNU/Linux-libre environment. The rest is up to you for a decision which way your system should take.


This wiki article is based on ParabolaWiki. We may have removed non-FSDG bits from it.