---
title: Optimized Repositories
description: Information about our optimized repositories
tableOfContents:
  minHeadingLevel: 1
  maxHeadingLevel: 4
---

import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
import ImageComponent from '~/components/image-component.astro';

To deliver a performance-optimized distribution, CachyOS recompiles Arch Linux packages specifically for the `x86-64-v3`, `x86-64-v4`, and `Zen4+` architectures.

- **x86-64-v3:** 5%-20% performance uplift compared to x86-64.
- **x86-64-v4:** Delivers substantial performance gains through AVX512 support, depending on the workload.
- **Zen 4/5:** In addition to the x86-64-v4 instruction set, the following instructions are added:

```text
abm, adx, aes, avx512bf16, avx512bitalg, avx512ifma, avx512vbmi, avx512vbmi2, avx512vnni,
avx512vpopctndq, clflushopt, clwb, clzero, fsgsbase, gfni, mwaitx, pclmul, pku, prfchw,
rpdid, rdrnd, rdseed, sha, sse4a, vaes, vockmulqdq, wbnoinvd, savec, xsaveopt, xsaves
```

To learn more about these architectures, [check this Wikipedia article](https://en.wikipedia.org/wiki/X86-64#Microarchitecture_levels).

## Customized Packages

Our [CachyOS-PKGBUILDs](https://github.com/CachyOS/CachyOS-PKGBUILDS) repository contains packages that receive ongoing updates, patches, and backported fixes.
To boost performance, we selectively implement PGO, LTO, and BOLT optimizations depending on the need.
We also maintain a couple of `-git` packages e.g mesa-git.

### [CachyOS Package Search](<https://packages.cachyos.org/>)

Introducing our new package search page for CachyOS. You can now easily search for packages and access detailed information, such as their compilation architecture, last update date, and more.

<ImageComponent imgsrc={import('~/assets/images/cachyos-package-dashboard.png')} />

## Migrating from x86-64-v3 to x86-64-v4 or znver4

If you’re currently using the x86-64-v3 repositories and your new CPU supports x86-64-v4 (or AMD Zen 4/5), you can migrate by following these steps:

### Checking CPU Compatibility

:::caution
Intel 12th gen (Alder Lake) and newer CPUs may report `x86-64-v4` support, but in practice they **cannot run AVX-512 instructions**.

Why?
- **Hybrid architecture conflict**: The big “P-cores” support AVX-512, but the small “E-cores” do not. Running AVX-512 while E-cores are active would cause instability.
- **Intel’s workaround**: To avoid this mismatch, Intel disabled AVX-512 in two ways:
  - **Microcode/BIOS updates** (early Alder Lake chips): AVX-512 could be re-enabled by avoiding or rolling back microcode updates.
  - **Hardware fusing** (later 2022+ chips): AVX-512 is permanently disabled at the factory, making it impossible to re-enable.

Because `x86-64-v4` requires AVX-512, these CPUs should be treated as **x86-64-v3 only**.
:::

- Verifying `x86-64-v4` support:
  ```sh title='Run the following command:'
  /lib/ld-linux-x86-64.so.2 --help | grep supported
  ```
  - ✅ `x86-64-v4 (supported, searched)` → CPU supports v4
  - ❌ No `x86-64-v4` line → CPU does not support v4

Example (CPU supports v4):
  ```sh
  $ /lib/ld-linux-x86-64.so.2 --help | grep supported
    x86-64-v2 (supported, searched)
    x86-64-v3 (supported, searched)
    x86-64-v4 (supported, searched)
  ```

- For AMD Zen 4/5 CPUs, check if your CPU reports znver4 or znver5:
  - Run the following command:
    ```sh
    gcc -march=native -Q --help=target 2>&1 | grep -Po "^\s+-march=\s+\K(\w+)\$"
    ```
    If the output is `znver4` or `znver5`, you can proceed with the migration.

:::note
Both x86-64-v4 and znver4 use the same mirrorlist `/etc/pacman.d/cachyos-v4-mirrorlist`.
:::

:::note[If you need to go back to a repository or revert the change, this guide will be useful to you.]
Example: From znver4 to v4.
:::

### Migration Steps

<Steps>
1. Edit `/etc/pacman.conf` and replace your `x86-64-v3` repositories with one of the following depending on your CPU support:
    <Tabs>
        <TabItem label="x86-64-v4">
            ```ini title='/etc/pacman.conf'
            [cachyos-v4]
            Include = /etc/pacman.d/cachyos-v4-mirrorlist

            [cachyos-core-v4]
            Include = /etc/pacman.d/cachyos-v4-mirrorlist

            [cachyos-extra-v4]
            Include = /etc/pacman.d/cachyos-v4-mirrorlist
            ```
        </TabItem>

        <TabItem label="znver4 (AMD Zen 4/5 only)">
          ```ini title='/etc/pacman.conf'
          [cachyos-znver4]
          Include = /etc/pacman.d/cachyos-v4-mirrorlist

          [cachyos-core-znver4]
          Include = /etc/pacman.d/cachyos-v4-mirrorlist

          [cachyos-extra-znver4]
          Include = /etc/pacman.d/cachyos-v4-mirrorlist
        ```
        </TabItem>
        Keep `[cachyos]`, `[core]`, `[extra]`, and `[multilib]` unchanged.
        </Tabs>
2. Clear the package cache and synchronize databases:

   ```sh
   sudo pacman -Scc   # Confirm with 'y' twice
   sudo pacman -Sy
   ```

3. Reinstall all packages to switch to the new architecture:

   ```sh
   pacman -Qqn | sudo pacman -S -
   ```

4. Reboot your system.
</Steps>

---

## Adding Our Repositories to an Existing Arch Linux Install

:::tip
Before considering adding our repositories, please take a look at the **[CPU compatibility list](/installation/installation_prepare#x86_64-microarchitecture-level-support)**
:::

<Tabs>

<TabItem label='Automated'>

We provide a script that automates the installation of our repositories to your existing Arch-based installs.

```sh
curl https://mirror.cachyos.org/cachyos-repo.tar.xz -o cachyos-repo.tar.xz
tar xvf cachyos-repo.tar.xz && cd cachyos-repo
sudo ./cachyos-repo.sh
```

:::tip[How the script works]
This script detects the instruction sets your CPU is capable of and installs whichever version of our repositories that
is most optimized for it. It also backs up your old `pacman.conf` for repository removal via the script.
:::

</TabItem>

<TabItem label='Manual'>
    :::caution
    Installing the CachyOS Pacman will install a forked pacman with features added from CachyOS, like "INSTALLED_FROM" and an automatic architecture check. Pacman 6.1 added a feature validation feature, which could lead when using the Arch Linux pacman into warnings. We are working with Arch Linux to provide a proper compatibility again. If you want to avoid this, don't add the "cachyos" repository, which contains the customized pacman. All other repositories like cachyos-v3, cachyos-v4, cachyos-extra/core-v3/4 are safe to add.
    :::

<Steps>

1. Install CachyOS keyring:

   ```sh
   # Import the repository key
   sudo pacman-key --recv-keys F3B607488DB35A47 --keyserver keyserver.ubuntu.com
   # Sign the repository key
   sudo pacman-key --lsign-key F3B607488DB35A47
   ```
2. Install the necessary packages:

   ```sh
   sudo pacman -U 'https://mirror.cachyos.org/repo/x86_64/cachyos/cachyos-keyring-20240331-1-any.pkg.tar.zst' \
   'https://mirror.cachyos.org/repo/x86_64/cachyos/cachyos-mirrorlist-27-1-any.pkg.tar.zst' \
   'https://mirror.cachyos.org/repo/x86_64/cachyos/cachyos-v3-mirrorlist-27-1-any.pkg.tar.zst' \
   'https://mirror.cachyos.org/repo/x86_64/cachyos/cachyos-v4-mirrorlist-27-1-any.pkg.tar.zst' \
   'https://mirror.cachyos.org/repo/x86_64/cachyos/pacman-7.1.0.r9.g54d9411-4-x86_64.pkg.tar.zst'
   ```
3. Add the CachyOS repositories to the pacman config file:
   :::note
   These repositories should be put above Arch Linux Repositories.
   :::

   ```ini
   # /etc/pacman.conf
   # If your CPU only supports x86-64, then add the [cachyos] repositories
   # cachyos repos
   [cachyos]
   Include = /etc/pacman.d/cachyos-mirrorlist

   # If your CPU supports x86-64-v3, then add [cachyos-v3],[cachyos-core-v3],[cachyos-extra-v3] and [cachyos]
   # cachyos repos

   [cachyos-v3]
   Include = /etc/pacman.d/cachyos-v3-mirrorlist
   [cachyos-core-v3]
   Include = /etc/pacman.d/cachyos-v3-mirrorlist
   [cachyos-extra-v3]
   Include = /etc/pacman.d/cachyos-v3-mirrorlist
   [cachyos]
   Include = /etc/pacman.d/cachyos-mirrorlist

   # If your CPU supports x86-64-v4, then add [cachyos-v4], [cachyos-core-v4], [cachyos-extra-v4] and [cachyos]
   # cachyos repos

   [cachyos-v4]
   Include = /etc/pacman.d/cachyos-v4-mirrorlist
   [cachyos-core-v4]
   Include = /etc/pacman.d/cachyos-v4-mirrorlist
   [cachyos-extra-v4]
   Include = /etc/pacman.d/cachyos-v4-mirrorlist
   [cachyos]
   Include = /etc/pacman.d/cachyos-mirrorlist

   # If your CPU is based on Zen 4 or Zen 5, add [cachyos-znver4], [cachyos-core-znver4], [cachyos-extra-znver4] and [cachyos]

   [cachyos-znver4]
   Include = /etc/pacman.d/cachyos-v4-mirrorlist
   [cachyos-core-znver4]
   Include = /etc/pacman.d/cachyos-v4-mirrorlist
   [cachyos-extra-znver4]
   Include = /etc/pacman.d/cachyos-v4-mirrorlist
   [cachyos]
   Include = /etc/pacman.d/cachyos-mirrorlist
   ```
      :::tip
   In order to make the transition from the `v4` repositories to the `znver4`

   Add the corresponding entries from the previous step and execute the following commands:
    ```sh
    sudo pacman -Scc # Enter Y in both instances
    sudo pacman -Sy
    pacman -Qqn | sudo pacman -S --needed - # To replace all the v4 packages with the znver4 packages
    # Reboot your system
    ```
   :::

4. Finally, update your system with CachyOS packages:
   ```sh
   sudo pacman -Syu
   ```

</Steps>

</TabItem>

</Tabs>

### Uninstalling CachyOS Repositories

<Tabs>
<TabItem label='Automated'>

**Run the following commands to remove the CachyOS repositories from your system:**
```sh
curl https://mirror.cachyos.org/cachyos-repo.tar.xz -o cachyos-repo.tar.xz
tar xvf cachyos-repo.tar.xz
cd cachyos-repo
sudo ./cachyos-repo.sh --remove
```

</TabItem>

<TabItem label='Manual'>

<Steps>

1. Reinstall the original pacman from Arch Linux:
   ```sh
   sudo pacman -S core/pacman
   ```
2. Execute the following command:
   ```sh
   # This avoids getting %INSTALLED_DB% warnings
   sudo find /var/lib/pacman/local/ -type f -name "desc" -exec sed -i '/^%INSTALLED_DB%$/,+2d' {} \;
   ```
3. Restore the pacman config file from backup:
   ```sh
   sudo mv /etc/pacman.conf.bak /etc/pacman.conf
   ```
4. Switch back to the default Arch Linux packages with the following commands:
   ```sh
   pacman -Qqn | sudo pacman -S -
   sudo pacman -Syu
   ```
</Steps>

</TabItem>
</Tabs>

## Tests and benchmarks

Michael from Phoronix has already benchmarked CachyOS a couple of times, which is shown mostly leading in the benchmark graphs and on the Geometric Mean of All Test Results.
Since the first benchmark made back in 2022, CachyOS has evolved and matured a lot more in terms of usability and performance.

If you would like to know more about the performance uplift from our repositories, please check the links below.

* **14/03/2021:** In a RFC discussion about the impact of x86-64-v3 was started by **Mateusz Jończyk** from Arch Linux showed some initial results.
  * [RFC: Use x86_64-v2 architecture](https://lists.archlinux.org/pipermail/arch-general/2021-March/048739.html)

* **09/12/2022:** First benchmark done by Michael.
  * [The Performance Of Arch Linux Powered CachyOS](https://www.phoronix.com/review/cachyos-linux-perf)

* **29/02/2024:** Phoronix conducted another benchmark demonstrating the difference between x86-64-v4, x86-64-v3 and x86-64 (generic) Packages. Looking at the examples like PHP or GCC, where we customize our PKGBUILDs there is a noticeable performance improvement.
  * [Arch Linux CachyOS Benchmarks Of x86-64-v3 & x86-64-v4 Repositories](https://www.phoronix.com/review/cachyos-x86-64-v3-v4)

* **20/08/2024:** Michael posted a new benchmark for the AMD Ryzen 9950x on which it includes CachyOS and some others Linux Distributions.
  * [Intel Continues To Show AMD The Importance Of Software Optimizations: 16% More Ryzen 9 9950X Performance](https://www.phoronix.com/review/linux-os-amd-ryzen9-9950x)
   :::note
   Liquid-DSP and RocksDB were compiled using the Phoronix Benchmark Suite, ignoring the compilation flags specified in /etc/makepkg.conf resulting in unexpected performance results for CachyOS.
   :::
