Skip to content

Arch Linux Reflector Guide

Jump to bottom
Mattscreative edited this page Dec 8, 2025 · 1 revision

Arch Linux Reflector Guide

Complete beginner-friendly guide to Reflector, a tool for ranking and updating Arch Linux mirror lists to improve download speeds and reliability.

Table of Contents

  1. What is Reflector?
  2. Installing Reflector
  3. Basic Usage
  4. Understanding Reflector Options
  5. Common Commands and Examples
  6. Ranking Mirrors Explained
  7. Refreshing Package Database
  8. Automating Mirror Updates
  9. Troubleshooting
  10. Summary

What is Reflector?

Overview

Reflector is a Python script that retrieves and ranks the latest Arch Linux mirrors by speed and updates the mirror list file (/etc/pacman.d/mirrorlist).

What Reflector does:

  • Tests mirror speeds: Downloads a small file from each mirror to measure speed
  • Ranks mirrors: Sorts mirrors by download speed (fastest first)
  • Filters mirrors: Can filter by country, protocol (HTTP/HTTPS), and other criteria
  • Updates mirror list: Automatically saves the ranked mirrors to your mirror list file

Why use Reflector?

  • Faster downloads: Uses the fastest available mirrors for your location
  • Better reliability: Tests mirrors to ensure they're working
  • Automatic updates: Can automatically update your mirror list
  • Easy to use: Simple command-line interface

What is a mirror?

  • A mirror is a server that contains a copy of the Arch Linux package repository
  • Multiple mirrors exist worldwide to distribute download load
  • Closer mirrors typically provide faster download speeds
  • If one mirror fails, pacman tries the next one in the list

Installing Reflector

Important Note: Reflector May Not Be Included by Default

Reflector may not be included in vanilla Arch Linux installations. It's recommended to check if it's installed first, and if not, install it manually using pacman. This is a common point of confusion for new Arch users.

Why it may not be included:

  • Arch Linux follows a minimal installation philosophy
  • Only essential packages are typically included by default
  • Reflector is an optional utility tool
  • Installation varies depending on the installation method

When you need it:

  • If you want to automatically rank and update mirrors
  • If you want faster download speeds
  • If you want to automate mirror management
  • If you're experiencing slow package downloads

Step 1: Check if Reflector is Already Installed

Before installing, check if Reflector is already installed:

which reflector

What this does:

  • Checks if the reflector command exists
  • Shows the path if installed
  • Shows nothing if not installed

If installed, you'll see:

/usr/bin/reflector

If not installed, you'll see:

(nothing - command not found)

Alternative check:

pacman -Q reflector

What this does:

  • Checks if the reflector package is installed
  • Shows version if installed
  • Shows error if not installed

If installed, you'll see:

reflector 2024.1-1

If not installed, you'll see:

error: package 'reflector' was not found

Step 2: Install Reflector

If Reflector is not installed, install it using pacman:

sudo pacman -S reflector

What this does:

  • sudo: Runs the command with administrator privileges (needed to install packages)
  • pacman: The package manager for Arch Linux
  • -S: Synchronize (install) the specified package
  • reflector: The name of the package to install

What you'll see: The system will show you what will be installed and ask for confirmation. Type Y and press Enter to proceed.

Example output:

:: Synchronizing package databases...
:: Starting full system upgrade...
resolving dependencies...
looking for conflicting packages...

Packages (1) reflector-2024.1-1

Total Download Size:    0.10 MiB
Total Installed Size:  0.50 MiB

:: Proceed with installation? [Y/n]

If you see "package not found":

  • Make sure your mirror list is working
  • Try updating your package database first: sudo pacman -Syy
  • Check your internet connection
  • Verify your mirror list is valid

If installation fails:

  • Check your internet connection
  • Update package database: sudo pacman -Syy
  • Try a different mirror (see troubleshooting section)
  • Check for system updates: sudo pacman -Syu

Step 3: Verify Installation

After installation, verify Reflector is installed and working:

reflector --version

What this does:

  • Shows the installed version of Reflector
  • Confirms the installation was successful
  • Verifies the command is accessible

Expected output:

Reflector 2024.1

If you see "command not found":

  • Installation may have failed
  • Try installing again: sudo pacman -S reflector
  • Check if the package was actually installed: pacman -Q reflector
  • Restart your terminal session

Test Reflector functionality:

reflector --list-countries

What this does:

  • Lists all available countries
  • Tests if Reflector can access mirror information
  • Verifies Reflector is working correctly

Expected output:

Available countries:
  Australia
  Austria
  Belgium
  Brazil
  ...
  United States
  ...

Installation on Different Arch-Based Distributions

CachyOS:

  • Reflector may or may not be pre-installed
  • Install the same way: sudo pacman -S reflector
  • Uses the same Arch Linux repositories

Manjaro:

  • Reflector is usually not pre-installed
  • Install the same way: sudo pacman -S reflector
  • May need to enable Arch repositories if not already enabled

EndeavourOS:

  • Reflector is usually not pre-installed
  • Install the same way: sudo pacman -S reflector

ArcoLinux:

  • Reflector may be pre-installed
  • Check first with: which reflector
  • Install if needed: sudo pacman -S reflector

Basic Usage

Quick Start Command

The most common Reflector command is:

sudo reflector --latest 20 --protocol https --sort rate --save /etc/pacman.d/mirrorlist

What this command does:

  • Gets the 20 latest mirrors (most recently synced)
  • Filters to only HTTPS mirrors (more secure)
  • Sorts mirrors by download rate (fastest first)
  • Saves the result to /etc/pacman.d/mirrorlist

Breaking it down:

  • sudo: Required because we're modifying a system file
  • reflector: The command to run
  • --latest 20: Get the 20 most recently synced mirrors
  • --protocol https: Only use HTTPS mirrors
  • --sort rate: Sort by download speed
  • --save /etc/pacman.d/mirrorlist: Save to the mirror list file

After Running Reflector

After updating your mirror list, refresh the package database:

sudo pacman -Syy

What this does:

  • -Syy: Force refresh of all package databases
  • Downloads fresh package lists from your new mirrors
  • Ensures pacman uses the updated mirror list

Why refresh?

  • The package database needs to be updated to use the new mirrors
  • -Syy forces a complete refresh (the double y means "force refresh")
  • This ensures all repositories are updated with the new mirror list

Understanding Reflector Options

Filtering Options

--latest <number>

What it does: Gets only the most recently synced mirrors.

Example:

--latest 20

What this means:

  • Only includes mirrors that have synced in the last 20 hours
  • Ensures mirrors are up-to-date
  • Excludes mirrors that haven't synced recently

Why use it:

  • Recent mirrors are more likely to be current
  • Reduces the chance of downloading outdated packages
  • Helps ensure mirror reliability

Common values:

  • --latest 5: Very recent mirrors only (5 hours)
  • --latest 10: Recent mirrors (10 hours)
  • --latest 20: Moderately recent mirrors (20 hours) - Recommended
  • --latest 50: Less strict (50 hours)

--protocol <protocol>

What it does: Filters mirrors by protocol (HTTP or HTTPS).

Options:

  • http: Unencrypted connections
  • https: Encrypted connections (more secure)

Example:

--protocol https

What this means:

  • Only uses mirrors that support HTTPS
  • All connections are encrypted
  • More secure than HTTP

Why use HTTPS:

  • Security: Encrypts data in transit
  • Privacy: Prevents interception of downloads
  • Verification: Ensures package integrity

When to use HTTP:

  • If HTTPS mirrors are slow in your area
  • For testing purposes
  • If you're on a trusted network

Example with HTTP:

--protocol http

--country <country>

What it does: Filters mirrors by country.

Example:

--country "United States"

What this means:

  • Only includes mirrors located in the specified country
  • Typically faster if you're in that country
  • Reduces latency

Multiple countries:

--country "United States,Canada"

What this means:

  • Includes mirrors from both countries
  • Useful if you're near a border
  • Provides more mirror options

Common countries:

  • "United States"
  • "Canada"
  • "United Kingdom"
  • "Germany"
  • "France"
  • "Australia"
  • "Japan"

Find your country name:

reflector --list-countries

What this does:

  • Lists all available countries
  • Shows exact country names to use
  • Helps you find the correct spelling

--age <hours>

What it does: Filters mirrors by how recently they synced (in hours).

Example:

--age 6

What this means:

  • Only includes mirrors that synced within the last 6 hours
  • More strict than --latest
  • Ensures very fresh mirrors

Difference from --latest:

  • --latest: Gets the N most recent mirrors
  • --age: Gets all mirrors that synced within N hours

When to use:

  • If you want very fresh mirrors
  • If you're concerned about mirror freshness
  • For critical updates

Sorting Options

--sort <criteria>

What it does: Sorts mirrors by a specific criteria.

Available criteria:

  1. rate - Sort by download speed (fastest first)

    --sort rate
    • Best for: Getting the fastest mirrors
    • What it does: Tests download speed and sorts by fastest
    • Recommended: Yes, for most users

  2. delay - Sort by connection delay (lowest first)

    --sort delay
    • Best for: Low latency connections
    • What it does: Sorts by ping time
    • Use when: You want responsive connections

  3. score - Sort by mirror score (highest first)

    --sort score
    • Best for: Overall mirror quality
    • What it does: Uses a combination of factors
    • Use when: You want balanced performance

  4. country - Sort by country name (alphabetical)

    --sort country
    • Best for: Organizing by location
    • What it does: Groups mirrors by country
    • Use when: You want geographic organization

  5. age - Sort by sync age (newest first)

    --sort age
    • Best for: Getting the freshest mirrors
    • What it does: Sorts by how recently mirrors synced
    • Use when: Freshness is more important than speed

Most common:

--sort rate
  • Recommended for most users
  • Gets the fastest mirrors
  • Best balance of speed and reliability

Output Options

--save <file>

What it does: Saves the generated mirror list to a file.

Example:

--save /etc/pacman.d/mirrorlist

What this means:

  • Saves the ranked mirrors to the mirror list file
  • Overwrites the existing mirror list
  • This is the file pacman uses

Important:

  • Always use sudo when saving to /etc/pacman.d/mirrorlist
  • This file requires administrator privileges to modify
  • Back up the original file first (see troubleshooting section)

Save to a different file:

--save /tmp/mirrorlist.new

What this does:

  • Saves to a temporary file
  • Allows you to review before replacing
  • Useful for testing

--number <number>

What it does: Limits the number of mirrors in the output.

Example:

--number 10

What this means:

  • Only includes the top 10 mirrors after sorting
  • Reduces mirror list size
  • Faster mirror selection for pacman

Why limit mirrors:

  • Smaller list = faster mirror selection
  • Top mirrors are usually sufficient
  • Reduces configuration complexity

Common values:

  • --number 5: Very few mirrors (fast selection)
  • --number 10: Moderate number (balanced)
  • --number 20: More mirrors (better redundancy)

Note: This is different from --latest. --latest filters by sync time, --number limits the final output.

Additional Options

--threads <number>

What it does: Sets the number of threads for testing mirrors.

Example:

--threads 5

What this means:

  • Tests 5 mirrors simultaneously
  • Faster execution
  • Uses more network bandwidth

Default: Usually 1 thread

When to increase:

  • If you have fast internet
  • If you want faster mirror testing
  • If testing many mirrors

When to decrease:

  • If you have slow internet
  • If you want to be conservative with bandwidth
  • If you're on a metered connection

--completion-percent <percent>

What it does: Only includes mirrors that have completed syncing to a certain percentage.

Example:

--completion-percent 100

What this means:

  • Only includes mirrors that are 100% synced
  • Ensures complete mirrors
  • Excludes partially synced mirrors

Common values:

  • 100: Only fully synced mirrors (recommended)
  • 99: Allows mirrors that are 99% synced
  • 95: More lenient

--exclude <pattern>

What it does: Excludes mirrors matching a pattern.

Example:

--exclude ".*\.edu"

What this means:

  • Excludes mirrors from .edu domains
  • Useful for avoiding slow academic mirrors
  • Can exclude specific domains

Use cases:

  • Excluding known slow mirrors
  • Avoiding specific domains
  • Filtering problematic mirrors

--include <pattern>

What it does: Only includes mirrors matching a pattern.

Example:

--include ".*\.org"

What this means:

  • Only includes mirrors from .org domains
  • Very restrictive filtering
  • Useful for specific requirements

Common Commands and Examples

Example 1: Basic Fast Mirrors (Recommended)

Command:

sudo reflector --latest 20 --protocol https --sort rate --save /etc/pacman.d/mirrorlist

What it does:

  • Gets 20 most recent mirrors
  • Only HTTPS mirrors
  • Sorts by download speed
  • Saves to mirror list

When to use:

  • Most common use case
  • Good balance of speed and security
  • Recommended for most users

After running:

sudo pacman -Syy

Example 2: Country-Specific Mirrors

Command:

sudo reflector --country "United States" --latest 20 --protocol https --sort rate --save /etc/pacman.d/mirrorlist

What it does:

  • Only US mirrors
  • 20 most recent
  • HTTPS only
  • Sorted by speed

When to use:

  • If you're in the United States
  • Want to prioritize local mirrors
  • Want faster local connections

After running:

sudo pacman -Syy

Example 3: Multiple Countries

Command:

sudo reflector --country "United States,Canada" --latest 20 --protocol https --sort rate --save /etc/pacman.d/mirrorlist

What it does:

  • Mirrors from US and Canada
  • 20 most recent
  • HTTPS only
  • Sorted by speed

When to use:

  • If you're near the US-Canada border
  • Want more mirror options
  • Want geographic diversity

After running:

sudo pacman -Syy

Example 4: Very Recent Mirrors Only

Command:

sudo reflector --age 6 --protocol https --sort rate --number 10 --save /etc/pacman.d/mirrorlist

What it does:

  • Only mirrors synced in last 6 hours
  • HTTPS only
  • Sorted by speed
  • Top 10 mirrors only

When to use:

  • Want very fresh mirrors
  • Want minimal mirror list
  • Prioritize freshness over quantity

After running:

sudo pacman -Syy

Example 5: Fastest Mirrors (No Country Filter)

Command:

sudo reflector --latest 50 --protocol https --sort rate --number 20 --save /etc/pacman.d/mirrorlist

What it does:

  • 50 most recent mirrors (any country)
  • HTTPS only
  • Sorted by speed
  • Top 20 fastest

When to use:

  • Want fastest mirrors regardless of location
  • Have very fast international connection
  • Want maximum speed

After running:

sudo pacman -Syy

Example 6: Low Latency Mirrors

Command:

sudo reflector --latest 20 --protocol https --sort delay --number 10 --save /etc/pacman.d/mirrorlist

What it does:

  • 20 most recent mirrors
  • HTTPS only
  • Sorted by connection delay (ping time)
  • Top 10 lowest latency

When to use:

  • Want responsive connections
  • Low latency is more important than raw speed
  • For interactive package operations

After running:

sudo pacman -Syy

Example 7: Save to Temporary File First

Command:

sudo reflector --latest 20 --protocol https --sort rate --save /tmp/mirrorlist.new

What it does:

  • Generates mirror list
  • Saves to temporary file
  • Allows review before replacing

Review the file:

cat /tmp/mirrorlist.new

If satisfied, replace the original:

sudo mv /tmp/mirrorlist.new /etc/pacman.d/mirrorlist

When to use:

  • Want to review mirrors before applying
  • Testing different configurations
  • Being cautious

After replacing:

sudo pacman -Syy

Example 8: HTTP Mirrors (If HTTPS is Slow)

Command:

sudo reflector --latest 20 --protocol http --sort rate --save /etc/pacman.d/mirrorlist

What it does:

  • 20 most recent mirrors
  • HTTP only (not HTTPS)
  • Sorted by speed

When to use:

  • HTTPS mirrors are slow in your area
  • On a trusted network
  • Need maximum speed

Security note:

  • HTTP is not encrypted
  • Use only on trusted networks
  • HTTPS is recommended when possible

After running:

sudo pacman -Syy

Ranking Mirrors Explained

How Mirror Ranking Works

What happens when you run Reflector:

  1. Mirror Discovery

    • Reflector gets a list of all available mirrors
    • Filters mirrors based on your criteria (country, protocol, etc.)

  2. Speed Testing

    • Downloads a small test file from each mirror
    • Measures download speed
    • Records connection delay (ping time)

  3. Ranking

    • Sorts mirrors by your chosen criteria (rate, delay, etc.)
    • Fastest/best mirrors first
    • Slowest/worst mirrors last

  4. Output

    • Generates a ranked mirror list
    • Saves to /etc/pacman.d/mirrorlist
    • pacman uses this list for downloads

Understanding Sort Criteria

Rate (Download Speed)

What it measures:

  • How fast data can be downloaded from the mirror
  • Measured in bytes per second (or similar)
  • Tests actual download performance

Best for:

  • Large package downloads
  • System updates
  • Maximum download speed

Example:

--sort rate

Delay (Connection Latency)

What it measures:

  • Time for a packet to reach the mirror and return (ping)
  • Measured in milliseconds
  • Lower is better

Best for:

  • Responsive connections
  • Small package downloads
  • Interactive operations

Example:

--sort delay

Score (Overall Quality)

What it measures:

  • Combination of factors
  • Overall mirror quality
  • Balanced metric

Best for:

  • General use
  • Balanced performance
  • When unsure which to choose

Example:

--sort score

Why Ranking Matters

Benefits of ranked mirrors:

  • Faster downloads: Fastest mirrors tried first
  • Better reliability: Tested mirrors are more reliable
  • Automatic optimization: No manual configuration needed
  • Geographic optimization: Can prioritize local mirrors

Without ranking:

  • pacman tries mirrors in order (may be slow)
  • No speed testing
  • Manual configuration required
  • May use slow mirrors

Refreshing Package Database

Why Refresh After Updating Mirrors?

After updating your mirror list, you should refresh the package database:

sudo pacman -Syy

What this does:

  • -S: Synchronize (refresh) package databases
  • yy: Force refresh (double y = force)
  • Downloads fresh package lists from new mirrors

Why it's important:

  • New mirrors need to be contacted
  • Package database needs updating
  • Ensures pacman uses new mirror list
  • Prevents stale package information

Understanding pacman -Syy

What -Syy means:

  • -S: Synchronize package databases
  • First y: Refresh package databases
  • Second y: Force refresh (even if up-to-date)

Difference from -Sy:

  • -Sy: Normal refresh (skips if up-to-date)
  • -Syy: Force refresh (always refreshes)

When to use -Syy:

  • After changing mirror list
  • After repository configuration changes
  • When package database seems stale
  • After Reflector updates

When to use -Sy:

  • Normal package database updates
  • Regular system updates
  • When you want to check for updates

Warning:

  • -Syy can cause issues if used incorrectly
  • Only use when necessary (after mirror changes)
  • For normal updates, use -Syu instead

Complete Workflow

Step 1: Update Mirrors

sudo reflector --latest 20 --protocol https --sort rate --save /etc/pacman.d/mirrorlist

Step 2: Refresh Package Database

sudo pacman -Syy

Step 3: Update System (Optional)

sudo pacman -Syu

What this workflow does:

  1. Updates mirror list with fastest mirrors
  2. Refreshes package database with new mirrors
  3. Updates system packages (if desired)

Automating Mirror Updates

Using systemd Timer (Recommended)

Create a systemd service file:

sudo nano /etc/systemd/system/reflector.service

Add this content:

[Unit]
Description=Pacman mirror list update
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/bin/reflector --latest 20 --protocol https --sort rate --save /etc/pacman.d/mirrorlist

What this does:

  • Creates a service that runs Reflector
  • Waits for network to be online
  • Updates mirror list when triggered

Create a systemd timer file:

sudo nano /etc/systemd/system/reflector.timer

Add this content:

[Unit]
Description=Run reflector weekly
Requires=reflector.service

[Timer]
OnCalendar=weekly
RandomizedDelaySec=0
Persistent=true

[Install]
WantedBy=timers.target

What this does:

  • Runs Reflector weekly
  • Random delay of 0 seconds (can be increased)
  • Persistent (runs if missed)

Enable and start the timer:

sudo systemctl enable reflector.timer
sudo systemctl start reflector.timer

What this does:

  • Enables timer to start on boot
  • Starts the timer immediately
  • Mirrors will update weekly automatically

Check timer status:

systemctl status reflector.timer

What this shows:

  • When timer will run next
  • Timer status
  • Last run time

Using Cron (Alternative)

Edit crontab:

sudo crontab -e

Add this line:

0 0 * * 0 /usr/bin/reflector --latest 20 --protocol https --sort rate --save /etc/pacman.d/mirrorlist && /usr/bin/pacman -Syy

What this does:

  • Runs every Sunday at midnight
  • Updates mirrors
  • Refreshes package database

Cron format explanation:

  • 0 0 * * 0: Sunday at 00:00 (midnight)
  • * * * * *: minute hour day month weekday

Troubleshooting

Issue: "Permission denied" Error

Error message:

Permission denied: /etc/pacman.d/mirrorlist

Solution: Use sudo when saving to /etc/pacman.d/mirrorlist:

sudo reflector --latest 20 --protocol https --sort rate --save /etc/pacman.d/mirrorlist

What this does:

  • sudo gives administrator privileges
  • Required for modifying system files
  • Always use sudo for this file

Issue: "No mirrors found"

Error message:

No mirrors found matching criteria

Possible causes:

  • Too restrictive filters
  • Network connectivity issues
  • Country name misspelled

Solutions:

1. Check country name:

reflector --list-countries

2. Use less restrictive filters:

sudo reflector --latest 50 --protocol https --sort rate --save /etc/pacman.d/mirrorlist

3. Remove country filter:

sudo reflector --latest 20 --protocol https --sort rate --save /etc/pacman.d/mirrorlist

4. Check network:

ping -c 3 8.8.8.8

Issue: Slow Mirror Testing

Problem: Reflector takes a long time to test mirrors.

Solutions:

1. Reduce number of mirrors tested:

sudo reflector --latest 10 --protocol https --sort rate --save /etc/pacman.d/mirrorlist

2. Use fewer threads (if using --threads):

sudo reflector --latest 20 --protocol https --sort rate --threads 1 --save /etc/pacman.d/mirrorlist

3. Test to temporary file first:

sudo reflector --latest 20 --protocol https --sort rate --save /tmp/mirrorlist.new

Issue: Backup Original Mirror List

Before running Reflector, backup your current mirror list:

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

What this does:

  • Creates a backup copy
  • Allows restoration if needed
  • Good practice before changes

Restore backup if needed:

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

Issue: Mirrors Still Slow After Update

Problem: Download speeds are still slow after updating mirrors.

Solutions:

1. Try different sort criteria:

sudo reflector --latest 20 --protocol https --sort delay --save /etc/pacman.d/mirrorlist

2. Increase number of mirrors:

sudo reflector --latest 50 --protocol https --sort rate --number 30 --save /etc/pacman.d/mirrorlist

3. Check your internet connection:

speedtest-cli

4. Try HTTP if HTTPS is slow:

sudo reflector --latest 20 --protocol http --sort rate --save /etc/pacman.d/mirrorlist

Issue: Package Database Errors After Update

Problem: Errors when running pacman -Syy after mirror update.

Solutions:

1. Verify mirror list is valid:

cat /etc/pacman.d/mirrorlist

2. Test a mirror manually:

curl -I https://mirror.example.com/archlinux/core/os/x86_64/

3. Restore backup and try again:

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

Issue: Reflector Command Not Found

Error message:

command not found: reflector

Solution: Install Reflector:

sudo pacman -S reflector

What this does:

  • Installs the Reflector package
  • Makes the command available
  • Required before first use

Summary

Key Points

What Reflector does:

  • Tests and ranks Arch Linux mirrors by speed
  • Updates your mirror list automatically
  • Improves download speeds

Most common command:

sudo reflector --latest 20 --protocol https --sort rate --save /etc/pacman.d/mirrorlist
sudo pacman -Syy

Important options:

  • --latest <number>: Get most recent mirrors
  • --protocol https: Use secure connections
  • --sort rate: Sort by download speed
  • --country "<country>": Filter by country
  • --save <file>: Save to mirror list file

After updating mirrors:

  • Always run sudo pacman -Syy to refresh package database
  • This ensures pacman uses the new mirrors
  • Required for changes to take effect

Best practices:

  • Backup mirror list before changes
  • Use HTTPS when possible
  • Test to temporary file first if unsure
  • Automate with systemd timer
  • Refresh package database after updates

Next Steps

Clone this wiki locally