CachyOS & Arch Workflow Guide for Experienced Linux Users

Introduction

This guide is intended for experienced Linux users transitioning to an Arch-based distribution, specifically CachyOS, which is built on Arch Linux. If you have previously used Debian-based (.deb) systems such as Ubuntu or Linux Mint, or RPM-based systems such as Fedora Linux or openSUSE, you are already familiar with core Linux administration concepts including package management, system updates, and terminal-based workflows.

Arch-based systems differ primarily in philosophy and tooling rather than inherent difficulty. They emphasize simplicity, transparency, full-system upgrades, and user control. Users are expected to understand the system components they install and maintain.

Important clarification:
This document focuses on CachyOS, which is based on Arch Linux but provides additional repositories, performance optimizations, and preconfigured tools.
Where workflows differ between CachyOS and pure Arch Linux, this guide explicitly notes the distinction.
System validation:
All commands and workflows documented in this guide were validated on an x86_64 (64-bit) system running CachyOS (February 2026 snapshot). Behavior on other architectures, such as ARM, may differ.
Scope Exclusion: Installation of CachyOS itself is not covered in this guide. It is assumed that the reader is already comfortable installing Linux distributions (e.g., Debian-based or RPM-based systems) and can complete a standard operating system installation without assistance.

What Is Different in Arch-Based Systems?

What This Guide Provides

This document focuses on post-installation workflows for CachyOS (based on Arch Linux).

If you are coming from Ubuntu, Fedora, or openSUSE, you are already familiar with core Linux concepts such as package management, system updates, and terminal workflows. This guide focuses specifically on the Arch-based approach to system management and development tooling.

Table of Contents

1. Installing yay (AUR helper)

# Install essential build tools
sudo pacman -S --needed base-devel git

# Install yay from cachyOS repository
sudo pacman -Syu yay

On CachyOS, yay is available directly via pacman. CachyOS provides yay in its repository; vanilla Arch does not.

Once installed, yay --version confirms yay is ready.

2. Searching for a package

# Search in official repos + AUR
yay -Ss package-name

# Example: search for SimpleScreenRecorder
yay -Ss simplescreenrecorder

Check descriptions, votes, and whether the package is in official repo or AUR.

# Optional: check detailed package info before installing
yay -Si simplescreenrecorder

3. Installing packages

3.1 Official repo package (use pacman)

# Example: Atril document viewer
sudo pacman -S atril

Pacman is faster and preferred for official repo packages.

3.2 AUR / community package (use yay)

# Example: Google Chrome
yay -S google-chrome

# Example: Zoom
yay -S zoom

# Example: SimpleScreenRecorder (stable version)
yay -S simplescreenrecorder

When prompted "Remove make dependencies after install? [y/N]", choose Y if you rarely build packages, or N if you plan to build more AUR packages soon.

4. Updating Your System and Packages (Using yay)

On CachyOS, yay can be used to update both official repository packages and AUR packages in a single command. 


# Update all packages (official repositories + AUR)
yay -Syu

- This performs a full system upgrade equivalent to pacman -Syu, while also checking and updating installed AUR packages.
- Recommended if you regularly install packages via yay.
- For more detailed explanations of update strategies and prompts, see Section 9.

5. Understanding package choices in AUR


# Stable version
yay -S simplescreenrecorder

# Git / development version (bleeding edge)
yay -S simplescreenrecorder-git

# Precompiled binary (faster build)
yay -S simplescreenrecorder-bin

# 32-bit support only if needed
yay -S lib32-simplescreenrecorder

Rule of thumb: use the stable version unless you need experimental features.

6. Installing cross-DE apps (e.g., MATE apps on XFCE)

# Example: Atril (MATE document viewer) on XFCE
sudo pacman -S atril

Arch is modular — only the required libraries are installed, not the full DE. Safe to use across DEs.

7. Key workflow summary

8. Examples of common apps

Web browser: yay -S google-chrome
Video conferencing: yay -S zoom
Screen recorder: yay -S simplescreenrecorder
Image viewer: yay -S viewnior
Document viewer (XFCE safe): sudo pacman -S atril

9. Updating the system

On CachyOS/Arch, updating is straightforward. You can update only official repo packages or include AUR packages as well.

9.1 Update official repository packages only


# Refresh package database and upgrade all official packages
sudo pacman -Syu

- Updates all installed packages from the official Arch repositories.
- Use this if you only installed packages from official repos and don’t have AUR packages.

9.2 Update official + AUR packages


# Update all packages including AUR packages
yay -Syu

- This refreshes both official repos and checks AUR packages for updates.
- Recommended if you installed apps via yay (AUR) like Chrome, Zoom, SimpleScreenRecorder.
- Single command keeps your system fully up-to-date.

Handling the "Packages to exclude" prompt:
- Sometimes yay will ask: Packages to exclude: (eg: "1 2 3", "1-3", "^4" or repo name)"
- This is optional and only used if you want to skip certain updates.
- Example from your system: core/wireless-regdb 2025.10.07-1 -> 2026.02.04-1
- Action: Simply press Enter to continue with the update. Excluding packages unnecessarily can cause partial upgrades and may break your system.

10. Python Project Management (pyenv + venv)

This section demonstrates the traditional and widely adopted approach to managing isolated Python versions and project-specific libraries using pyenv together with venv.

Alternative approach:
If you prefer a modern, integrated workflow, you may skip this section and proceed directly to Section 12, which introduces uv.

uv provides Python version management and dependency resolution in a single toolchain and is an excellent alternative to the pyenv + venv combination.

Note: Python 3.14.3 is a stable, final release of the Python 3.14 series, officially published on February 3, 2026, and includes numerous bug fixes and improvements.

10.1 Install Python with pyenv


# Install pyenv from AUR
yay -S pyenv

# Install a specific Python version
pyenv install 3.14.3

# Set it as global or local for the project
pyenv global 3.14.3
# OR for project only:
pyenv local 3.14.3

# Verify installation
python --version

10.2 Create your project folder


# Move to your home directory
cd ~

# Create a project folder
mkdir climate_analysis

# Go inside the folder
cd climate_analysis

10.3 Initialize a virtual environment (replaces uv init)


# Create virtual environment named 'venv'
python -m venv venv

10.4 Activate the virtual environment

Activation command depends on your shell:

- While active, all Python libraries are isolated from the system.
- Prompt changes to indicate the virtual environment is active (e.g., (venv) ~/climate_analysis).

10.5 Install project-specific libraries (replaces uv add ...)


pip install \
xarray netCDF4 numpy h5netcdf cftime scipy scikit-learn matplotlib \
cartopy cdsapi pandas dask osmnx geopy statsmodels

- All packages are installed only in this environment.
- Dependencies are automatically resolved, similar to uv.

10.6 Installing additional libraries later (like uv add seaborn)


# Activate the virtual environment first (choose Bash or fish command from above)
# Then install the additional library
pip install seaborn

10.7 Optional: Reproduce your environment elsewhere


# Save installed libraries
pip freeze > requirements.txt

# Recreate environment on another machine
python -m venv venv
source venv/bin/activate  # or activate.fish if using fish shell
pip install -r requirements.txt

- Fully isolates your project from system Python.
- Desktop environment independent.

11. Migrating to a new Python version inside a project

Virtual environments are tied to a specific Python version. To use a newer Python version, you must create a new venv and migrate your packages.

11.1 Install the new Python version with pyenv


# Example: install Python 3.14.3
pyenv install 3.14.3

# Set it for the project directory (optional)
pyenv local 3.14.3

11.2 Create a new virtual environment with the new Python


# In your project folder
python -m venv venv-new

# Activate the new environment
# Bash / zsh / sh:
source venv-new/bin/activate
# fish shell:
source venv-new/bin/activate.fish

11.3 Migrate installed packages from the old venv


# Activate old environment
source venv/bin/activate  # or activate.fish

# Export installed packages
pip freeze > requirements.txt

# Deactivate old environment
deactivate

# Activate new environment
source venv-new/bin/activate  # or activate.fish

# Install all packages in the new environment
pip install -r requirements.txt

11.4 Optional: Replace old venv


# Remove old venv
rm -rf venv

# Rename new venv to original name
mv venv-new venv

- Virtual environments cannot be upgraded in place; migration is the safest way.
- This ensures your project uses the latest Python version while keeping all previous packages.
- Old environment can be retained until migration is verified.

12. Python Project Management (uv)

uv is a modern Python package and environment manager that integrates Python version management and dependency resolution into a single toolchain.

Note:
In most development workflows, uv can fully replace the pyenv + venv combination by providing interpreter management and isolated project environments in one unified system. 

# Update system packages
sudo pacman -Syu

# Install uv from the CachyOS extra repository
sudo pacman -S uv python-uv python-uv-build

- On pure Arch Linux, package names or repository availability may differ. Consult the Arch Wiki if packages are unavailable.
- uv installs the Rust-based Python package manager.
- python-uv provides the Python wrapper for running uv commands.
- python-uv-build is used when building Python packages with uv.
- Installing these ensures you can run uv python install, uv init, and uv add in your projects.

12.2 Install System Build Dependencies


# Required for building Python and scientific packages
sudo pacman -Syu base-devel zlib xz bzip2 libffi openssl proj geos

12.3 Create Project Directory


# Create and navigate to your project folder
mkdir climate_analysis
cd climate_analysis

12.4 Install Python with uv

Note: Python 3.14.3 is a stable, final release of the Python 3.14 series, officially published on February 3, 2026, and includes numerous bug fixes and improvements.


# Install exact Python version
uv python install 3.14.3

12.5 Initialize Project Environment

Now that Python 3.14.3 is installed, you can create a fully isolated project environment using uv. This ensures your project dependencies are separated from the system Python, avoiding conflicts and improving reproducibility.

# Initialize a new uv-managed environment for this project
uv init --python 3.14.3

- This creates a hidden directory (usually .uv) in your project folder containing the isolated Python interpreter and packages.
- To install packages in this environment, use uv add <package>.
- To run scripts within the environment, use uv run python <script.py> or activate the environment for interactive use.

12.6 Add Climate and Scientific Libraries


uv add xarray netCDF4 numpy h5netcdf cftime scipy \
scikit-learn matplotlib cartopy cdsapi pandas dask osmnx geopy statsmodels

- Cartopy may require system libraries (installed in step 12.1) to build correctly.
- All packages are installed in the uv-managed environment, isolated from system Python.

12.7 Verify Installation


uv run python - << 'EOF'
import xarray, netCDF4, numpy, cartopy, cdsapi, pandas
print("OK")
EOF

Expected output: OK

12.8 Create Synthetic Temperature Map


# Create a Python file using your preferred editor
# gedit test_map.py
# or: xed test_map.py
# or: mousepad test_map.py

# Paste the following code:
import xarray as xr
import numpy as np
import matplotlib.pyplot as plt
import cartopy.crs as ccrs

lons = np.linspace(-180, 180, 360)
lats = np.linspace(-90, 90, 180)
data = 15 + 8 * np.random.randn(180, 360)

ds = xr.DataArray(
    data,
    coords=[lats, lons],
    dims=['lat', 'lon'],
    name='temp'
)

fig = plt.figure(figsize=(10, 6))
ax = plt.axes(projection=ccrs.Robinson())
ax.coastlines()
ax.stock_img()
ax.gridlines(draw_labels=True, dms=True, x_inline=False, y_inline=False)

ds.plot(
    ax=ax,
    transform=ccrs.PlateCarree(),
    cmap='RdBu_r',
    add_colorbar=True
)

plt.title("Synthetic Global Temperature Map")
plt.savefig('0_test_map.png', dpi=300, bbox_inches='tight')
plt.savefig('0_test_map.pdf', bbox_inches='tight')

print("Analysis complete. Images saved to your folder.")

12.9 Run the Script Using uv


uv run python test_map.py

- Output files: 0_test_map.png (high-res image) and 0_test_map.pdf (vector format).
- Environment is fully isolated and uses Python 3.14.3, ensuring reproducibility.

13. Comparing pyenv + venv vs uv Workflow on CachyOS

This section highlights the differences, pros, and use cases for managing Python projects using pyenv + venv (sections 10–11) versus the uv workflow on CachyOS (section 12).

13.1 Python Version Management

13.2 Environment Isolation

13.3 Library Installation

13.4 Reproducibility

13.5 Use Cases

13.6 Key Takeaways

- You can even combine both: install a Python version with pyenv, then manage project-specific packages with uv if desired.
- For climate analysis, uv ensures that Python version and dependencies remain consistent across machines, preventing environment-related errors.

14. Package Removal, Maintenance & Arch Philosophy

14.1 Removing Packages


# Remove a package
sudo pacman -R package-name

# Remove a package + unused dependencies
sudo pacman -Rs package-name

# Remove a package + unused dependencies + config files
sudo pacman -Rns package-name

# Remove AUR package (same logic via yay)
yay -Rns package-name

Use -Rns if you want a completely clean removal. This prevents leftover configuration files and unused libraries.

14.2 Cleaning the Package Cache


# Remove old cached versions (keep current installed versions)
sudo pacman -Sc

# Remove ALL cached packages (use with caution)
sudo pacman -Scc

# Same via yay
yay -Sc

# Cleaner long-term cache maintenance (recommended)
# Keeps the last 3 versions of each package, removes older versions
sudo pacman -S pacman-contrib   # if not installed
sudo paccache -r

Arch stores downloaded packages in /var/cache/pacman/pkg. Cleaning the cache occasionally prevents unnecessary disk usage. Tip: Using paccache is safer than -Scc because it keeps a few recent package versions. This prevents issues if you need to downgrade a package later.

14.3 Removing Orphan Packages


# List orphan packages (unused dependencies)
pacman -Qtdq

# Remove all orphan packages
sudo pacman -Rns $(pacman -Qtdq)

Orphan packages accumulate over time. Cleaning them keeps your system minimal and tidy.

14.4 Arch Philosophy (Important)

On CachyOS and other Arch-based systems, avoid partial upgrades. Partial upgrades are unsupported and may break the system.


# Correct way to update
sudo pacman -Syu

# Or include AUR
yay -Syu

Always upgrade the full system. Do not update single packages without refreshing and upgrading everything. 


# ❌ NEVER do this:
sudo pacman -Sy package-name

Using -Sy without -u causes partial upgrades and can break your system. Arch expects a fully synchronized and upgraded system at all times.

15. Installing LaTeX and TeX Studio

This section explains how to set up a complete LaTeX environment on CachyOS, similar to "Full TeX" on most distros, and how to install the TeX Studio editor.

15.1 Install TeX Live


# Update system first
sudo pacman -Syu

# Install TeX Live meta package (core + most commonly used packages)
sudo pacman -S texlive-meta

- texlive-meta provides a complete LaTeX environment for most documents. - Only install extra packages (e.g., fonts, languages) if a document/script requires them later: sudo pacman -S texlive-fontsextra texlive-formatsextra texlive-publishers texlive-langcjk

15.2 Install TeX Studio editor


# Official repo version (recommended)
sudo pacman -S texstudio

# Optional: AUR precompiled version (faster install, latest upstream)
# yay -S texstudio-bin

- texstudio integrates with TeX Live automatically. - Launch via terminal: texstudio or from the application menu. - Recommended for stability and automatic updates via pacman.

15.3 Minimal workflow example


# Update system
sudo pacman -Syu

# Install LaTeX environment
sudo pacman -S texlive-meta

# Install TeX Studio editor
sudo pacman -S texstudio

# Launch TeX Studio
texstudio

This setup is fast, clean, and fully functional for compiling LaTeX documents. Additional packages can be installed as needed without reinstalling everything.

16. Setting Up SDKMAN! and JDK 17 on CachyOS

This section demonstrates a proven workflow for installing SDKMAN!, a specific JDK (17.0.8-tem), and preparing CachyOS for Java/JavaFX development. Validated on CachyOS (February 2026) using Bash.

Note: CachyOS uses fish as the default shell. For the SDKMAN! and JavaFX setup instructions below (Bash commands and aliases), you should temporarily start a Bash shell by running: 


bash
This will open a Bash session where the commands and aliases work as written. You can exit Bash anytime by typing exit to return to Fish.

16.1 Install System Dependencies


# Ensure required utilities are installed
sudo pacman -Syu zip unzip p7zip curl tar

These tools are required for SDKMAN! to download and extract JDKs correctly.

16.2 Install SDKMAN!


# Download and run SDKMAN! installer
# URL: https://sdkman.io/
curl -s "https://get.sdkman.io" | bash

# Load SDKMAN! into current shell
source "$HOME/.sdkman/bin/sdkman-init.sh"

# Verify installation
sdk version

SDKMAN! provides a simple way to install and manage multiple Java versions on your system.

16.3 Install JDK 17.0.8-tem


# List available JDKs
sdk list java

# Install the specific version
sdk install java 17.0.8-tem

# Set it as default
sdk default java 17.0.8-tem

You now have JDK 17.0.8-tem installed and set as the default for all Java projects.

16.4 Verify JDK Installation


# Check Java runtime version
java -version

# Check Java compiler version
javac -version

Both commands should show version 17.0.8, confirming that SDKMAN! is active.

16.5 Download and Prepare JavaFX SDK

To use JavaFX with JDK 17, download the official JavaFX SDK from Gluon and prepare it for your projects.


# Create a folder for the JavaFX SDK
mkdir -p ~/javafx-sdk
cd ~/javafx-sdk

# Download the JavaFX 17.0.18 SDK (Linux x64)
# URL: https://gluonhq.com/products/javafx/
wget https://download2.gluonhq.com/openjfx/17.0.18/openjfx-17.0.18_linux-x64_bin-sdk.zip \
     -O openjfx-17.0.18-sdk.zip

# Unzip the SDK
unzip openjfx-17.0.18-sdk.zip

# Verify the contents
ls ~/javafx-sdk/javafx-sdk-17.0.18/lib
# Should show jars including javafx-controls.jar and javafx-fxml.jar

Keep this folder as your JavaFX SDK location. All projects can reference these jars directly. Using version 17.0.18 ensures full compatibility with JDK 17 and includes all modules, including javafx.fxml.

16.6 (Optional) Create Project Folder

Prepare a local project folder for your JavaFX projects. No need to copy JavaFX jars — all projects will reference the global SDK for efficiency and portability.


# Create project folder
mkdir ~/javafx_project
cd ~/javafx_project

# Your project code will go here
# No need to copy the SDK jars; we will reference the global SDK

Referencing the global SDK saves disk space and ensures consistency across multiple projects. All projects will use the same JavaFX 17.0.18 modules from the shared SDK at ~/javafx-sdk/javafx-sdk-17.0.18/lib.

16.7 Create Convenient Aliases for JavaFX (Global SDK)

Define Bash aliases to simplify compiling and running JavaFX projects, pointing directly to the shared JavaFX 17.0.18 SDK.


# Path to the global JavaFX SDK
JAVA_FX_LIB=~/javafx-sdk/javafx-sdk-17.0.18/lib

# Bash aliases for compilation and running
alias javacfx='javac --module-path $JAVA_FX_LIB \
    --add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media,javafx.web,javafx.swing'
alias javafx='java --module-path $JAVA_FX_LIB \
    --add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media,javafx.web,javafx.swing'

# Usage:
# JavaFX source code example at: 
https://www.tutorialspoint.com/javafx/javafx_rotate_transition.htm
# Compile the JavaFX source code:
javacfx RotateTransitionExample.java

# Run it
javafx RotateTransitionExample

- These aliases work reliably with SDKMAN! JDK 17 (or newer).
- Uses all major JavaFX modules: controls, fxml, graphics, media, web, swing.
- Minimal disk usage: one global SDK is shared across all projects.
- Portable across systems as long as the same JDK version and SDK path are maintained.

16.8 Make JavaFX Aliases Permanent

By default, aliases defined in a terminal exist only for the current session. To avoid redefining them every time, you can make them permanent.

Important: CachyOS defaults to the fish shell. You can either set aliases in Fish or temporarily switch to Bash for Bash-style aliases.

Option 1: Permanent Bash Aliases

If you prefer Bash aliases, start a Bash session first:


bash

Then edit your Bash configuration:


gedit ~/.bashrc

Add the following lines at the end:


# JavaFX 17.0.18 SDK path
export JAVA_FX_LIB=~/javafx-sdk/javafx-sdk-17.0.18/lib

# JavaFX aliases
alias javacfx='javac --module-path $JAVA_FX_LIB --add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media,javafx.web,javafx.swing'
alias javafx='java --module-path $JAVA_FX_LIB --add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media,javafx.web,javafx.swing'

Save and reload:


source ~/.bashrc

Option 2: Permanent Fish Functions

To define persistent JavaFX commands in Fish:


# Set universal variable for JavaFX SDK
set -Ux JAVA_FX_LIB ~/javafx-sdk/javafx-sdk-17.0.18/lib

# Define compile function
function javacfx
    javac --module-path $JAVA_FX_LIB --add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media,javafx.web,javafx.swing $argv
end

# Define run function
function javafx
    java --module-path $JAVA_FX_LIB --add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media,javafx.web,javafx.swing $argv
end

With this guide, you should be able to confidently manage CachyOS and Arch-based workflows, leveraging pacman and yay to maintain a clean, transparent, and fully updatable system.

References