Skip to content

CachyOS Repository Configuration

Jump to bottom
Mattscreative edited this page Dec 5, 2025 · 3 revisions

CachyOS Repository Configuration Guide

Complete beginner-friendly guide to configuring package repositories on CachyOS, including mirror selection, repository priorities, and optimization.

Table of Contents

  1. Understanding Repositories
  2. Repository Configuration File
  3. Mirror Configuration
  4. Repository Priorities
  5. Optimizing Repository Performance
  6. Adding Custom Repositories
  7. Troubleshooting Repository Issues

Understanding Repositories

What are Repositories?

Repositories are servers that store and serve software packages.

What they do:

  • Store packages: Contain compiled software packages
  • Serve packages: Provide packages for download
  • Maintain metadata: Keep package information up to date
  • Provide security: Packages are signed and verified

Why repositories matter:

  • Package availability: Determines what software you can install
  • Update speed: Faster mirrors = faster updates
  • Reliability: Good mirrors = reliable package downloads
  • Performance: Closer mirrors = faster downloads

CachyOS Repositories

Core repositories:

  • core: Essential system packages
  • extra: Additional software packages
  • community: Community-maintained packages
  • multilib: 32-bit packages (for 64-bit systems)

CachyOS-specific repositories:

  • cachyos: CachyOS optimized packages
  • cachyos-v3: x86-64-v3 optimized packages
  • cachyos-v4: x86-64-v4 optimized packages
  • cachyos-zen4: Zen4 optimized packages

What each repository contains:

  • core: Essential system packages (kernel, base system)
  • extra: Additional software (applications, libraries)
  • community: Community-maintained packages
  • multilib: 32-bit compatibility packages
  • cachyos-*: Optimized versions of packages

Repository Configuration File

Configuration File Location

Main configuration file:

/etc/pacman.conf

What this file does:

  • Defines which repositories to use
  • Sets repository priorities
  • Configures package signing
  • Sets download options

Viewing Configuration

View current configuration:

cat /etc/pacman.conf

What you'll see:

  • Repository sections
  • Mirror list locations
  • Package signing settings
  • Download options

Edit configuration:

sudo nano /etc/pacman.conf

What this does:

  • Opens configuration file for editing
  • Requires administrator privileges
  • Make changes carefully

Configuration File Structure

Example configuration:

[options]
HoldPkg     = pacman glibc
Architecture = auto
CheckSpace
SigLevel    = Required DatabaseOptional
LocalFileSigLevel = Optional

[core]
Include = /etc/pacman.d/mirrorlist

[extra]
Include = /etc/pacman.d/mirrorlist

[community]
Include = /etc/pacman.d/mirrorlist

What each section means:

[options]:

  • HoldPkg: Packages to never update
  • Architecture: System architecture (auto-detected)
  • CheckSpace: Check disk space before installing
  • SigLevel: Package signing requirements
  • LocalFileSigLevel: Local file signing

[core], [extra], [community]:

  • Repository sections
  • Include: Points to mirror list file
  • Each repository has its own section

Repository Options

Common options for repositories:

Server:

Server = https://mirror.example.com/repo/$arch/$repo

What this does:

  • Defines download server
  • $arch: Architecture (x86_64)
  • $repo: Repository name (core, extra, etc.)

SigLevel:

SigLevel = Required

What this does:

  • Requires package signatures
  • Verifies package integrity
  • Security feature

Usage:

Usage = All

What this does:

  • All: Use for all operations
  • Sync: Use only for syncing
  • Search: Use only for searching

Mirror Configuration

What are Mirrors?

Mirrors are copies of repositories on different servers.

Why mirrors matter:

  • Speed: Closer mirrors = faster downloads
  • Reliability: Multiple mirrors = backup if one fails
  • Load distribution: Spreads download load
  • Geographic location: Closer = lower latency

Mirror List File

Mirror list location:

/etc/pacman.d/mirrorlist

What this file does:

  • Lists available download servers
  • pacman uses fastest available mirror
  • Can prioritize specific mirrors

View mirror list:

cat /etc/pacman.d/mirrorlist

Example content:

##
## CachyOS repository mirrorlist
##

Server = https://mirror.cachyos.org/repo/x86_64/cachyos
Server = https://mirror.example.com/repo/x86_64/cachyos
Server = https://another-mirror.com/repo/x86_64/cachyos

What this means:

  • Each Server = line is a mirror
  • pacman tries mirrors in order
  • Uses first available mirror

Ranking Mirrors by Speed

Install mirror ranking tool:

sudo pacman -S pacman-contrib

What this does:

  • Installs rankmirrors tool
  • Tests mirror speeds
  • Ranks mirrors by performance

Rank mirrors:

rankmirrors -n 6 /etc/pacman.d/mirrorlist

What this does:

  • -n 6: Test top 6 mirrors
  • Tests download speed
  • Shows fastest mirrors

Rank and save:

rankmirrors -n 6 /etc/pacman.d/mirrorlist > /tmp/mirrorlist.ranked
sudo mv /tmp/mirrorlist.ranked /etc/pacman.d/mirrorlist

What this does:

  • Ranks mirrors
  • Saves to temporary file
  • Replaces mirror list with ranked version

** Warning**: Backup original first:

sudo cp /etc/pacman.d/mirrorlist /etc/pacman.d/mirrorlist.backup

Manual Mirror Selection

Edit mirror list:

sudo nano /etc/pacman.d/mirrorlist

Prioritize specific mirrors:

  • Move preferred mirrors to top
  • Comment out slow mirrors (add #)
  • Uncomment fast mirrors (remove #)

Example:

# Fast mirror (uncommented = active)
Server = https://fast-mirror.com/repo/x86_64/cachyos

# Slow mirror (commented = inactive)
# Server = https://slow-mirror.com/repo/x86_64/cachyos

What this does:

  • Uncommented mirrors are used
  • Commented mirrors are ignored
  • pacman uses first available uncommented mirror

Finding Good Mirrors

Check mirror status:

  • Visit CachyOS website
  • Check mirror status page
  • Test mirror speeds manually

Test mirror speed:

curl -o /dev/null -s -w "%{time_total}\n" https://mirror.example.com/repo/x86_64/cachyos/core.db

What this does:

  • Downloads small file from mirror
  • Measures download time
  • Lower time = faster mirror

Compare mirrors:

  • Test multiple mirrors
  • Choose fastest ones
  • Update mirror list

Repository Priorities

What are Repository Priorities?

Repository priorities determine which repository pacman uses when multiple repositories have the same package.

Why priorities matter:

  • Package selection: Which version to install
  • Optimization level: Prefer optimized packages
  • Conflict resolution: Resolve package conflicts

Setting Priorities

Priority syntax:

[repository-name]
Server = ...
Priority = 100

What this does:

  • Priority = 100: Sets priority level
  • Higher number = higher priority
  • pacman prefers higher priority repositories

Example:

[cachyos-v3]
Server = https://mirror.cachyos.org/repo/x86_64/cachyos-v3
Priority = 100

[extra]
Server = https://mirror.cachyos.org/repo/x86_64/extra
Priority = 50

What this means:

  • cachyos-v3 has priority 100
  • extra has priority 50
  • If both have same package, pacman uses cachyos-v3

Priority Best Practices

Recommended priorities:

  • CachyOS optimized repos: Priority 100 (highest)
  • Official repos: Priority 50 (medium)
  • Community repos: Priority 25 (lower)

Why:

  • Prefer optimized packages
  • Fall back to official if optimized unavailable
  • Use community as last resort

Example configuration:

[cachyos-v3]
Priority = 100

[core]
Priority = 50

[extra]
Priority = 50

[community]
Priority = 25

Optimizing Repository Performance

Update Frequency

Update package database regularly (use -Syu for full update):

# Always use -Syu together to avoid dependency issues
sudo pacman -Syu

What this does:

  • Downloads latest package information
  • Updates local package database
  • Required before installing new packages

Full system update:

sudo pacman -Syu

What this does:

  • Updates package database
  • Upgrades all installed packages
  • Keeps system current

Recommended frequency:

  • Weekly: For regular users
  • Before major changes: Always update first
  • After long time: Update before installing

Parallel Downloads

Enable parallel downloads:

sudo nano /etc/pacman.conf

Find [options] section, add:

ParallelDownloads = 5

What this does:

  • Downloads 5 packages simultaneously
  • Faster package installation
  • Reduces total download time

Recommended values:

  • 5: Good balance (recommended)
  • 10: Faster but more bandwidth
  • 1: Slower but more reliable

After editing:

  • Changes apply immediately
  • No restart needed
  • Test with next package install

Download Speed Limits

Limit download speed (optional):

sudo nano /etc/pacman.conf

Add to [options] section:

XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-connection-per-server=2 --max-tries=2 --min-split-size=5M --no-conf --remote-time=true --summary-interval=0 --timeout=5 --dir=/ --out %o %u

What this does:

  • Uses aria2 for downloads
  • Better download management
  • Resume interrupted downloads

Install aria2:

sudo pacman -S aria2

Benefits:

  • Resume interrupted downloads
  • Better download management
  • More reliable downloads

Adding Custom Repositories

When to Add Custom Repositories

Reasons to add custom repos:

  • Specialized packages: Packages not in official repos
  • Testing packages: Beta or testing versions
  • Third-party software: Software from other sources
  • Custom builds: Your own package builds

** Warning**: Only add repositories you trust!

Adding a Repository

Edit pacman.conf:

sudo nano /etc/pacman.conf

Add repository section:

[custom-repo]
Server = https://example.com/repo/$arch
SigLevel = Optional

What this does:

  • [custom-repo]: Repository name
  • Server: Download server URL
  • SigLevel: Package signing level

Add repository key (if signed):

sudo pacman-key --add repository-key.pub
sudo pacman-key --lsign-key repository-key-id

What this does:

  • Adds repository signing key
  • Verifies package signatures
  • Required for signed repositories

Update package database (use -Syu for full update):

# Always use -Syu together to avoid dependency issues
sudo pacman -Syu

What this does:

  • Downloads repository metadata
  • Makes packages available
  • Verifies repository is working

Example: Adding AUR Helper Repository

Some AUR helpers have repositories:

[chaotic-aur]
Server = https://cdn-mirror.chaotic.cx/$repo/$arch
SigLevel = Never

** Warning**: SigLevel = Never disables signature checking (less secure)

Update (use -Syu for full update):

# Always use -Syu together to avoid dependency issues
sudo pacman -Syu

Troubleshooting Repository Issues

Repository Not Found

Error:

error: failed retrieving file 'package.pkg.tar.zst' from mirror: The requested URL returned error: 404

Solutions:

  1. Update package database (use -Syu for full update):

    # Always use -Syu together to avoid dependency issues
sudo pacman -Syu

  2. Check mirror status:

  • Mirror may be down
  • Try different mirror
  • Check CachyOS website
  1. Check repository configuration: 
    cat /etc/pacman.conf
  • Verify repository is enabled
  • Check mirror list

Slow Downloads

Issues:

  • Mirror is slow
  • Network connection is slow
  • Mirror is overloaded

Solutions:

  1. Rank mirrors:

    rankmirrors -n 6 /etc/pacman.d/mirrorlist

  2. Change mirror:

  • Edit mirror list
  • Move faster mirrors to top
  • Test different mirrors
  1. Enable parallel downloads:
  • Add ParallelDownloads = 5 to pacman.conf
  • Faster package installation

Signature Errors

Error:

error: package-name: signature from "..." is unknown trust

Solutions:

  1. Update keyring:

    sudo pacman-key --refresh-keys

  2. Initialize keyring:

    sudo pacman-key --init
sudo pacman-key --populate archlinux

  3. Check repository signature:

  • Verify repository is signed
  • Check SigLevel in pacman.conf

Repository Sync Errors

Error:

error: failed to synchronize all databases

Solutions:

  1. Check internet connection:

    ping -c 3 8.8.8.8

  2. Check mirror availability:

  • Test mirror manually
  • Try different mirror

  1. Clear package cache:

    sudo pacman -Sc

  2. Update keyring:

    sudo pacman-key --refresh-keys

Additional Resources

Summary

This guide covered:

  1. Understanding repositories - What they are and why they matter
  2. Repository configuration - Editing pacman.conf
  3. Mirror configuration - Selecting and ranking mirrors
  4. Repository priorities - Setting package preferences
  5. Performance optimization - Parallel downloads, speed optimization
  6. Custom repositories - Adding third-party repositories
  7. Troubleshooting - Common repository issues

Key Takeaways:

  • Repositories store and serve software packages
  • Mirror selection affects download speed
  • Use rankmirrors to find fastest mirrors
  • Set repository priorities to prefer optimized packages
  • Enable parallel downloads for faster installation
  • Only add trusted custom repositories
  • Update package database regularly

This guide is based on the CachyOS Wiki and Arch Linux Wiki and expanded with detailed explanations for beginners. For the most up-to-date repository information, always refer to the official documentation.

Clone this wiki locally