- Notifications
You must be signed in to change notification settings - Fork584
Arch Linux installer - guided, templates etc.
License
archlinux/archinstall
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
Just another guided/automatedArch Linux installer with a twist.The installer also doubles as a python library to install Arch Linux and manage services, packages, and other things inside the installed system(Usually from a live medium).
- archinstalldiscord server
- archinstall#archinstall:matrix.org Matrix channel
- archinstall#archinstall@irc.libera.chat:6697
- archinstalldocumentation
sudo pacman -S archinstall
Alternative ways to install aregit clone
the repository orpip install --upgrade archinstall
.
Running theguided installer
Assuming you are on an Arch Linux live-ISO or installed viapip
:
archinstall
Running theguided installer usinggit
# cd archinstall-git# python -m archinstall
Some additional options that most users do not need are hidden behind the--advanced
flag.
archinstall
can be run with a JSON configuration file. There are 2 different configuration files to consider,theuser_configuration.json
contains all general installation configuration, whereas theuser_credentials.json
contains the sensitive user configuration such as user password, root password, and encryption password.
An example of the user configuration file can be found hereconfiguration fileand an example of the credentials configuration herecredentials file.
HINT: The configuration files can be auto-generated by startingarchinstall
, configuring all desired menupoints and then going toSave configuration
.
To load the configuration file intoarchinstall
run the following command
archinstall --config<path to user config file or URL> --creds<path to user credentials config file or URL>
If you come across any issues, kindly submit your issue here on Github or post your query in thediscord help channel.
When submitting an issue, please:
- Provide the stacktrace of the output if applicable
- Attach the
/var/log/archinstall/install.log
to the issue ticket. This helps us help you!- To extract the log from the ISO image, one way is to use
curl -F'file=@/var/log/archinstall/install.log' https://0x0.st
- To extract the log from the ISO image, one way is to use
Archinstall is available in different languages which have been contributed and are maintained by the community.The language can be switched inside the installer (first menu entry). Bear in mind that not all languages providefull translations as we rely on contributors to do the translations. Each language has an indicator that showshow much has been translated.
Any contributions to the translations are more than welcome,to get started please followthe guide
The ISO does not ship with all fonts needed for different languages.Fonts that use a different character set than Latin will not be displayed correctly. If those languageswant to be selected then a proper font has to be set manually in the console.
All available console fonts can be found in/usr/share/kbd/consolefonts
and set withsetfont LatGrkCyr-8x16
.
There are some examples in theexamples/
directory that should serve as a starting point.
The following is a small example of how to script your owninteractive installation:
frompathlibimportPathfromarchinstallimportInstaller,ProfileConfiguration,profile_handler,Userfromarchinstall.default_profiles.minimalimportMinimalProfilefromarchinstall.lib.disk.device_modelimportFilesystemTypefromarchinstall.lib.disk.encryption_menuimportDiskEncryptionMenufromarchinstall.lib.disk.filesystemimportFilesystemHandlerfromarchinstall.lib.interactions.disk_confimportselect_disk_configfs_type=FilesystemType('ext4')# Select a device to use for the installationdisk_config=select_disk_config()# Optional: ask for disk encryption configurationdata_store= {}disk_encryption=DiskEncryptionMenu(disk_config.device_modifications,data_store).run()# initiate file handler with the disk config and the optional disk encryption configfs_handler=FilesystemHandler(disk_config,disk_encryption)# perform all file operations# WARNING: this will potentially format the filesystem and delete all datafs_handler.perform_filesystem_operations()mountpoint=Path('/tmp')withInstaller(mountpoint,disk_config,disk_encryption=disk_encryption,kernels=['linux'])asinstallation:installation.mount_ordered_layout()installation.minimal_installation(hostname='minimal-arch')installation.add_additional_packages(['nano','wget','git'])# Optionally, install a profile of choice.# In this case, we install a minimal profile that is emptyprofile_config=ProfileConfiguration(MinimalProfile())profile_handler.install_profile_config(installation,profile_config)user=User('archinstall','password',True)installation.create_users(user)
This installer will perform the following actions:
- Prompt the user to configure the disk partitioning
- Prompt the user to setup disk encryption
- Create a file handler instance for the configured disk and the optional disk encryption
- Perform the disk operations (WARNING: this will potentially format the disks and erase all data)
- Install a basic instance of Arch Linux(base base-devel linux linux-firmware btrfs-progs efibootmgr)
- Install and configures a bootloader to partition 0 on UEFI. On BIOS, it sets the root to partition 0.
- Install additional packages(nano, wget, git)
- Create a new user
To create your own ISO with this script in it: FollowArchISO's guide on creating your own ISO.
For an example of a fully scripted, automated installation please refer to the examplefull_automated_installation.py
Archinstall comes with anunattendedexample which will look for a matching profile for the machine it is being run on, based on any local MAC address.For instance, if the machine the code is executed on has the MAC address52:54:00:12:34:56
it will look for a profile called52-54-00-12-34-56.py.If it's found, the unattended installation will begin and source that profile as its installation procedure.
archinstall
comes with a set of pre-configured profiles available for selection during the installation process.
The profiles' definitions and the packages they will install can be directly viewed in the menu, ordefault profiles
If you want to test a commit, branch, or bleeding edge release from the repository using the standard Arch Linux Live ISO image,replace the archinstall version with a newer one and execute the subsequent steps defined below.
*Note: When booting from a live USB, the space on the ramdisk is limited and may not be sufficient to allowrunning a re-installation or upgrade of the installer. In case one runs into this issue, any of the following can be used
- Resize the root partitionhttps://wiki.archlinux.org/title/Archiso#Adjusting_the_size_of_the_root_file_system
- The boot parameter
copytoram=y
(https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio-archiso/-/blob/master/docs/README.bootparams#L26)can be specified which will copy the root filesystem to tmpfs.*
- You need a working network connection
- Install the build requirements with
pacman -Sy; pacman -S git python-pip gcc pkgconf
(note that this may or may not work depending on your RAM and current state of the squashfs maximum filesystem free space) - Uninstall the previous version of archinstall with
pip uninstall --break-system-packages archinstall
- Now clone the latest repository with
git clone https://github.com/archlinux/archinstall
- Enter the repository with
cd archinstall
At this stage, you can choose to check out a feature branch for instance withgit checkout v2.3.1-rc1
- To run the source code, there are 2 different options:
- Run a specific branch version from source directly using
python -m archinstall
, in most cases this will work just fine, therare case it will not work is if the source has introduced any new dependencies that are not installed yet - Installing the branch version with
pip install --break-system-packages .
andarchinstall
- Run a specific branch version from source directly using
To test this without a live ISO, the simplest approach is to use a local image and create a loop device.
This can be done by installingpacman -S arch-install-scripts util-linux
locally and doing the following:
# truncate -s 20G testimage.img# losetup --partscan --show --find ./testimage.img# pip install --upgrade archinstall# python -m archinstall --script guided# qemu-system-x86_64 -enable-kvm -machine q35,accel=kvm -device intel-iommu -cpu host -m 4096 -boot order=d -drive file=./testimage.img,format=raw -drive if=pflash,format=raw,readonly,file=/usr/share/ovmf/x64/OVMF_CODE.fd -drive if=pflash,format=raw,readonly,file=/usr/share/ovmf/x64/OVMF_VARS.fd
This will create a20 GBtestimage.img
and create a loop device which we can use to format and install to.archinstall
is installed and executed inguided mode. Once the installation is complete,you can use qemu/kvm to boot the test media.
(You'd actually need to do some EFI magic in order to point the EFI vars to the partition 0 in the test medium, so this won't work entirely out of the box, but that gives you a general idea of what we're going for here)
There's also aBuilding and Testing guide.
It will go through everything from packaging, building and running(with qemu) the installer against a dev branch.
For a description of the problem seehttps://archinstall.archlinux.page/help/known_issues.html#keyring-is-out-of-date-2213 and discussion in issue#2213.
For a quick fix the below command will install the latest keyrings
pacman -Sy archlinux-keyring
To install Arch Linux alongside an existing Windows installation usingarchinstall
, follow these steps:
- Ensure some unallocated space is available for the Linux installation after the Windows installation.
- Boot into the ISO and run
archinstall
. - Choose
Disk configuration
->Manual partitioning
. - Select the disk on which Windows resides.
- Select
Create a new partition
. - Choose a filesystem type.
- Determine the start and end sectors for the new partition location (values can be suffixed with various units).
- Assign the mountpoint
/
to the new partition. - Assign the
Boot/ESP
partition the mountpoint/boot
from the partitioning menu. - Confirm your settings and exit to the main menu by choosing
Confirm and exit
. - Modify any additional settings for your installation as necessary.
- Start the installation upon completion of setup.
Archinstall promises to ship aguided installer that followstheArch Linux Principles as well as a library to manage services, packages, and other Arch Linux aspects.
The guided installer ensures a user-friendly experience, offering optional selections throughout the process. Emphasizing its flexible nature, these options are never obligatory.In addition, the decision to use the guided installer remains entirely with the user, reflecting the Linux philosophy of providing full freedom and flexibility.
Archinstall primarily functions as a flexible library for managing services, packages, and other elements within an Arch Linux system.This core library is the backbone for the guided installer that Archinstall provides. It is also designed to be used by those who wish to script their own custom installations.
Therefore, Archinstall will try its best to not introduce any breaking changes except for major releases which may break backward compatibility after notifying about such changes.
Please seeCONTRIBUTING.md
About
Arch Linux installer - guided, templates etc.