archinstall(1)

archinstall

You can always get the latest options for this file with archinstall --dry-run, this executes the guided installer in a safe mode where no permanent actions will be taken on your system but simulate a run and save the configuration to disk.

archinstall --config config.json

archinstall --config-url https://domain.lan/config.json

{
  "additional-repositories": [],
  "archinstall-language": "English",
  "audio_config": null,
  "bootloader_config": {
    "bootloader": "Systemd-boot",
    "uki": false,
    "removable": false
  },
  "bootloader": "Systemd-boot",
  "debug": false,
  "disk_config": {
    "config_type": "manual_partitioning",
    "device_modifications": [
      {
        "device": "/dev/sda",
        "partitions": [
          {
            "btrfs": [],
            "flags": [
              "boot"
            ],
            "fs_type": "fat32",
            "length": {
              "sector_size": null,
              "total_size": null,
              "unit": "B",
              "value": 99982592
            },
            "mount_options": [],
            "mountpoint": "/boot",
            "obj_id": "369f31a8-2781-4d6b-96e7-75680552b7c9",
            "start": {
              "sector_size": {
                "sector_size": null,
                "total_size": null,
                "unit": "B",
                "value": 512
              },
              "total_size": null,
              "unit": "sectors",
              "value": 34
            },
            "status": "create",
            "type": "primary"
          },
          {
            "btrfs": [],
            "flags": [],
            "fs_type": "fat32",
            "length": {
              "sector_size": null,
              "total_size": null,
              "unit": "B",
              "value": 100000000
            },
            "mount_options": [],
            "mountpoint": "/efi",
            "obj_id": "13cf2c96-8b0f-4ade-abaa-c530be589aad",
            "start": {
              "sector_size": {
                "sector_size": null,
                "total_size": null,
                "unit": "B",
                "value": 512
              },
              "total_size": {
                "sector_size": null,
                "total_size": null,
                "unit": "B",
                "value": 16106127360
              },
              "unit": "MB",
              "value": 100
            },
            "status": "create",
            "type": "primary"
          },
          {
            "btrfs": [],
            "flags": [],
            "fs_type": "ext4",
            "length": {
              "sector_size": null,
              "total_size": null,
              "unit": "B",
              "value": 15805127360
            },
            "mount_options": [],
            "mountpoint": "/",
            "obj_id": "3e75d045-21a4-429d-897e-8ec19a006e8b",
            "start": {
              "sector_size": {
                "sector_size": null,
                "total_size": null,
                "unit": "B",
                "value": 512
              },
              "total_size": {
                "sector_size": null,
                "total_size": null,
                "unit": "B",
                "value": 16106127360
              },
              "unit": "MB",
              "value": 301
            },
            "status": "create",
            "type": "primary"
          }
        ],
        "wipe": false
      }
    ]
  },
  "disk_encryption": {
    "encryption_type": "luks",
    "partitions": [
      "3e75d045-21a4-429d-897e-8ec19a006e8b"
    ]
  },
  "hostname": "archlinux",
  "kernels": [
    "linux"
  ],
  "locale_config": {
    "kb_layout": "us",
    "sys_enc": "UTF-8",
    "sys_lang": "en_US"
  },
  "mirror_config": {
    "custom_servers": [
      {
        "url": "https://mymirror.com/$repo/os/$arch"
      }
    ],
    "mirror_regions": {
      "Australia": [
        "http://archlinux.mirror.digitalpacific.com.au/$repo/os/$arch"
      ]
    },
    "optional_repositories": [
      "testing"
    ],
    "custom_repositories": [
      {
        "name": "myrepo",
        "url": "https://myrepo.com/$repo/os/$arch",
        "sign_check": "Required",
        "sign_option": "TrustAll"
      }
    ]
  },
  "network_config": {},
  "no_pkg_lookups": false,
  "ntp": true,
  "offline": false,
  "packages": [],
  "parallel downloads": 0,
  "profile_config": null,
  "save_config": null,
  "script": "guided",
  "silent": false,
  "swap": true,
  "timezone": "UTC",
  "version": "2.6.0"
}

All key and value entries must conform to the JSON standard. Below is human readable examples with links, effectively breaking the syntax. Adapt the descriptions below to suit your needs and the JSON format.

Scroll to the right in the table to see required options.

If no entries are found in disk_config, archinstall guided installation will use whatever is mounted currently under /mnt/archinstall without performing any disk operations.

{
    "root_enc_password" : "SecretSanta2022"
}

users is optional only if root_enc_password was set. users will be enforced otherwise and the minimum amount of users with sudo privileges required will be set to 1.

{
    "config_type": "pre_mounted_config",
    "mountpoint": "/mnt/archinstall"
}

/mnt/archinstall    (/dev/sda2)
     ├── boot       (/dev/sda1)
     └── home       (/dev/sda3)

Some disk layouts can be too complicated to detect, such as RAID setups. Please do report those setups on the Issue Tracker <https://github.com/archlinux/archinstall> so we can support them.

This mode will wipe data!

Note that this options is similar to the manual partitioning but is generated through the menu system! And the best effort layout might deviate slightly from some wiki guidelines in order to facilitate some optional configurations at a later stage.

{
    "disk_config": {
        "config_type": "default_layout",
        "device_modifications": [
            {
                "device": "/dev/sda",
                "wipe": true,
                "partitions": "..."
            }
        ]
    }
}

{
     "disk_config": {
         "config_type": "manual_partitioning",
         "device_modifications": [
            "filesystem struct"
         ]
     }
 }

Important to note that the units and positions in the examples below — are highly user specific!

{
        "btrfs": [],
        "flags": [
           "boot"
        ],
        "fs_type": "fat32",
        "length": {
           "sector_size": null,
           "total_size": null,
           "unit": "B",
           "value": 99982592
        },
        "mount_options": [],
        "mountpoint": "/boot",
        "obj_id": "369f31a8-2781-4d6b-96e7-75680552b7c9",
        "start": {
           "sector_size": {
               "sector_size": null,
               "total_size": null,
               "unit": "B",
               "value": 512
           },
           "total_size": null,
           "unit": "sectors",
           "value": 34
        },
        "status": "create",
        "type": "primary"
}

The Boot flag will make archinstall automatically set the correct ESP partition GUID if the system is booted with EFI support. The GUID will then be set to C12A7328-F81F-11D2-BA4B-00A0C93EC93B.

     {
   "btrfs": [],
   "flags": [],
   "fs_type": "ext4",
   "length": {
      "sector_size": null,
      "total_size": null,
      "unit": "B",
      "value": 15805127360
   },
   "mount_options": [],
   "mountpoint": "/",
   "obj_id": "3e75d045-21a4-429d-897e-8ec19a006e8b",
   "start": {
      "sector_size": {
         "sector_size": null,
         "total_size": null,
         "unit": "B",
         "value": 512
      },
      "total_size": {
         "sector_size": null,
         "total_size": null,
         "unit": "B",
         "value": 16106127360
      },
      "unit": "MB",
      "value": 301
   },
   "status": "create",
   "type": "primary"
}

Note that the "mountpoint": null is used for the overall partition, and instead individual subvolumes have mountpoints set.

{
   "btrfs": [
       {
           "mountpoint": "/",
           "name": "@"
       },
       {
           "mountpoint": "/home",
           "name": "@home"
       },
       {
           "mountpoint": "/var/log",
           "name": "@log"
       },
       {
           "mountpoint": "/var/cache/pacman/pkg",
           "name": "@pkg"
       }
   ],
   "dev_path": null,
   "flags": [],
   "fs_type": "btrfs",
   "mount_options": [
       "compress=zstd"
   ],
   "mountpoint": null,
   "obj_id": "d712357f-97cc-40f8-a095-24ff244d4539",
   "size": {
       "sector_size": {
           "unit": "B",
           "value": 512
       },
       "unit": "B",
       "value": 15568207872
   },
   "start": {
       "sector_size": {
           "unit": "B",
           "value": 512
       },
       "unit": "MiB",
       "value": 513
   },
   "status": "create",
   "type": "primary"
}

If you know your time is correct on the machine, you can run archinstall --skip-ntp to ignore time sync.

# killall gpg-agent
# rm -rf /etc/pacman.d/gnupg
# pacman-key --init
# pacman-key --populate
# pacman -Sy archlinux-keyring
# systemctl restart archlinux-keyring-wkd-sync.timer

If you know the ISO is the latest, and that you have valid GPG keys, try archinstall --skip-wkd to ignore waiting for the sync.

If you skip WKD sync, you might end up with:

> error: archinstall: signature from "Anton Hvornum (Torxed) <[email protected]>" is unknown trust
> :: File /var/cache/pacman/pkg/archinstall-1.2.3-4-x86_64.pkg.tar.xz is corrupted (invalid or corrupted package (PGP signature)).
> Do you want to delete it? [Y/n]

The issue can happen on new ISO's too even as little as a few days after release, as some keys might expire right after the keyring is "burnt in" to the ISO.

Another common issue relating to the network not being configured, is that time might not be set correctly - resulting in the keyring not being able to update. See Waiting for time sync #2144.

But in spirit of giving the community options, archinstall supports Python Plugins <#archinstall-plugins>, which means you can run archinstall --plugin <url> and source an AUR plugin.

torxed/archinstall-aur <https://github.com/torxed/archinstall-aur> is a reference implementation for plugins:

# archinstall --plugin https://archlinux.life/aur-plugin

phisch/archinstall-aur <https://github.com/phisch/archinstall-aur> is another alternative:

# archinstall --plugin https://raw.githubusercontent.com/phisch/archinstall-aur/master/archinstall-aur.py

Warning:

An easy way to submit logs is archinstall share-log, which uploads install.log to paste.rs and prints a shareable URL.
Use caution when submitting other log files, but archinstall pledges to keep install.log safe for posting publicly!

We only try to guarantee that /var/log/archinstall/install.log is free from sensitive information. Any other log file should be pasted with utmost care!

pacman -S archinstall

pip install archinstall

git clone https://github.com/archlinux/archinstall

import archinstall

$ cd archinstall
$ python -m build .
$ python -m installer dist/*.whl

This is subject to change in the future as this method is currently a bit stiff. The script path will become a parameter. But for now, this is by design.

from archinstall.lib.disk.device_handler import device_handler
from pprint import pprint
pprint(device_handler.devices)

[
    BDevice(
        disk=<parted.disk.Disk object at 0x7fbe17156050>,
        device_info=_DeviceInfo(
            model='PC801 NVMe SK hynix 512GB',
            path=PosixPath('/dev/nvme0n1'),
            type='nvme',
            total_size=Size(value=512110190592, unit=<Unit.B: 1>,
            sector_size=SectorSize(value=512, unit=<Unit.B: 1>)),
            free_space_regions=[
                <archinstall.lib.disk.device.DeviceGeometry object at 0x7fbe166c4250>,
                <archinstall.lib.disk.device.DeviceGeometry object at 0x7fbe166c4c50>,
                <archinstall.lib.disk.device.DeviceGeometry object at 0x7fbe166c4a10>],
            sector_size=SectorSize(value=512, unit=<Unit.B: 1>),
            read_only=False,
            dirty=False
        ),
        partition_infos=[
            _PartitionInfo(
                partition=<parted.partition.Partition object at 0x7fbe166c4a90>,
                name='primary',
                type=<PartitionType.PRIMARY: 'primary'>,
                fs_type=<FilesystemType.FAT32: 'fat32'>,
                path='/dev/nvme0n1p1',
                start=Size(value=2048, unit=<Unit.sectors: 'sectors'>, sector_size=SectorSize(value=512, unit=<Unit.B: 1>)),
                length=Size(value=535822336, unit=<Unit.B: 1>, sector_size=SectorSize(value=512, unit=<Unit.B: 1>)),
                flags=[
                    <PartitionFlag.BOOT: flag_id=1, alias=None>,
                    <PartitionFlag.ESP: flag_id=18, alias=None>
                ],
                partn=1,
                partuuid='a26be943-c193-41f4-9930-9341cf5f6b19',
                uuid='6EE9-2C00',
                disk=<parted.disk.Disk object at 0x7fbe17156050>,
                mountpoints=[
                    PosixPath('/boot')
                ],
                btrfs_subvol_infos=[]
            ),
            _PartitionInfo(...)
        ]
    )
]

Most calls, including the one above requires root <https://en.wikipedia.org/wiki/Superuser> privileges.

def on_pacstrap(*packages):
    ...