CachyOS for WSL

BEFORE ANYTHING ELSE: run 'bd onboard' and follow the instruction

A custom Windows Subsystem for Linux (WSL) distribution based on CachyOS, an optimized Arch Linux distribution.

Features

🚀 CachyOS Base - Built on CachyOS with optimized packages and performance tweaks
🎨 Custom Branding - CachyOS icon, Windows Terminal color scheme with signature teal/cyan accents
⚙️ systemd Support - Modern init system with properly configured services for WSL
🔒 Secure Setup - OOBE (Out-of-Box Experience) creates user with sudo access
📦 Pacman Package Manager - Access to Arch Linux and CachyOS repositories
🔄 Windows Integration - Seamless interoperability with Windows

Requirements

Windows 10/11 with WSL 2 support
WSL 2.4.4 or later (check with wsl --version)
Administrator privileges (for installation)

Quick Start

Option 1: Direct Installation (Recommended)

Download cachyos-v3.wsl from Releases

Open PowerShell and run:

wsl --install --from-file path\to\cachyos-v3.wsl

Follow the OOBE prompts to create your user account
Start using CachyOS WSL!

Option 2: Local Testing (Developers)

For testing the distribution locally before wider distribution:

Clone this repository
Download the built .wsl file or build from source

Run the test script in PowerShell (as Administrator):

.\scripts\override-manifest.ps1 -TarPath .\dist\cachyos-v3.wsl
wsl --install cachyos-wsl-v1

See Testing Guide for detailed testing procedures.

Post-Install Configuration

Windows Terminal Profile Setup

When installing with wsl --install --from-file, the Windows Terminal profile isn't automatically created. Run the post-install script to configure it:

# Interactive setup (recommended)
.\scripts\setup-terminal.ps1

# Or use the advanced script
.\scripts\Setup-WindowsTerminalProfile.ps1 -SetAsDefault

This will:

✅ Add CachyOS to Windows Terminal with custom colors
✅ Export and configure the CachyOS icon
✅ Set up the Nord-based color scheme with signature teal/cyan accents
✅ Optionally set CachyOS as your default profile

See scripts/README.md for more details and troubleshooting.

Note: This step is only needed for manual installations with --from-file. Microsoft Store distributions (when available) will configure Windows Terminal automatically.

Building from Source

Prerequisites

Linux machine with Docker installed
Make, tar, gzip
ImageMagick (for icon conversion)

Build Steps

# Clone the repository
git clone https://github.com/dwalleck/cachyos-wsl.git
cd cachyos-wsl

# Build the rootfs (requires Docker)
make rootfs

# Create the .wsl file
cd dist
cp cachyos-v3-rootfs.tar.gz cachyos-v3.wsl

The resulting dist/cachyos-v3.wsl file can be installed on Windows.

First Run Experience

On first launch, you'll see:

============================================
Welcome to CachyOS for WSL!
============================================

Please create a default user account.
This user will have administrative privileges via sudo.

For more information visit: https://wiki.cachyos.org/

Enter new UNIX username:

The OOBE script will:

Create your user account with UID 1000
Add you to the wheel group for sudo access
Configure sudo permissions
Initialize the pacman keyring for package management
Set you as the default user for future launches

Package Management

CachyOS WSL uses pacman as its package manager:

# Update package databases
sudo pacman -Sy

# Search for packages
pacman -Ss <package-name>

# Install packages
sudo pacman -S <package-name>

# Update all packages
sudo pacman -Syu

# Remove packages
sudo pacman -R <package-name>

Available Repositories

core - Essential Arch Linux packages
extra - Additional Arch Linux packages
multilib - 32-bit libraries
cachyos - CachyOS-specific optimized packages
cachyos-v3 - x86-64-v3 optimized packages (5-20% performance improvement)
cachyos-core-v3 - x86-64-v3 optimized core packages
cachyos-extra-v3 - x86-64-v3 optimized extra packages

Shell Configuration

CachyOS WSL includes three shells with full CachyOS customizations:

Fish (Default Shell)

Fish is set as the default shell, providing a modern command-line experience with:

Syntax highlighting - Commands are colored as you type
Autosuggestions - Fish suggests commands from your history
CachyOS customizations - System maintenance aliases, enhanced utilities
Enhanced utilities - Uses eza for colorful file listings, bat for syntax-highlighted file viewing
fastfetch greeting - Displays system information on shell startup

Fish Features

# CachyOS-specific aliases
update          # Update mirror list and upgrade system
cleanup         # Remove orphaned packages
mirror          # Run cachyos-rate-mirrors for optimal performance
rip             # List recent package installations

# Enhanced commands (automatically aliased)
ls → eza        # Modern ls with colors and icons
ll → eza -al    # Long listing format
cat → bat       # Syntax-highlighted file viewing

Zsh (Alternative Shell)

Zsh is available with oh-my-zsh and Powerlevel10k theme:

Powerlevel10k prompt - Fast, customizable, beautiful prompt
Oh-My-Zsh framework - Plugins: git, fzf, extract
CachyOS aliases - Same system maintenance shortcuts as Fish
Enhanced suggestions - Fish-style autosuggestions and syntax highlighting

To switch to Zsh:

chsh -s /usr/bin/zsh

Then log out and log back in for the change to take effect.

Bash (Fallback Shell)

Bash remains available as a traditional, POSIX-compatible fallback:

chsh -s /bin/bash

Shell Features Comparison

Feature	Fish	Zsh	Bash
Syntax highlighting	✅	✅ (plugin)	❌
Autosuggestions	✅	✅ (plugin)	❌
CachyOS aliases	✅	✅	❌
Enhanced utilities (eza, bat)	✅	✅	❌
POSIX compatible	❌	✅	✅
Default shell	✅	❌	❌

Fonts for Best Experience

For optimal visual experience (icons in file listings, fancy prompts), use a Nerd Font in your Windows Terminal:

Fantasque Sans Mono Nerd Font (included in distribution)
Cascadia Code Nerd Font
FiraCode Nerd Font

Configure in Windows Terminal Settings → Profiles → CachyOS → Appearance → Font face.

Configuration

WSL Configuration

Located at /etc/wsl.conf:

systemd enabled
Network auto-generation enabled
Windows interop enabled
Windows PATH appended

Distribution Configuration

Located at /etc/wsl-distribution.conf:

OOBE script: /usr/lib/wsl/oobe.sh
Default UID: 1000
Custom icon: /usr/lib/wsl/cachyos.ico
Terminal profile: /usr/lib/wsl/terminal-profile.json

Windows Terminal Integration

The distribution includes configuration for a Windows Terminal profile with:

Nord-based dark theme - Matches CachyOS desktop aesthetic
Signature cyan colors - CachyOS branding (#1dc7b5, #00ccff)
CachyOS icon - Custom branding for the profile
Starts in home directory - Opens in ~ by default

Note: For manual installations, you need to run the post-install script to apply this configuration. See Post-Install Configuration above.

Troubleshooting

Package Signature Errors

If you encounter signature errors with pacman:

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

OOBE Doesn't Run

Manually run the OOBE script:

sudo /usr/lib/wsl/oobe.sh

systemd Issues

Verify systemd is enabled:

cat /etc/wsl.conf  # Check [boot] systemd = true
systemctl status   # Should show "running"

Documentation

Testing Guide - Comprehensive testing procedures
OOBE Research - Design decisions for user setup
Branding Research - CachyOS colors and assets
WSL Configuration Research - WSL config details
PowerShell Testing - Local testing approach

Project Structure

cachyos-wsl/
├── build/               # Build scripts
│   ├── build-rootfs.sh  # Main build orchestration
│   ├── cleanup.sh       # WSL-specific cleanup
│   └── packages.list    # Package list for rootfs
├── config/              # Configuration files
│   ├── oobe.sh          # First-run user setup script
│   ├── wsl.conf         # WSL per-distribution settings
│   ├── wsl-distribution.conf  # Distribution metadata
│   ├── terminal-profile.json  # Windows Terminal colors
│   ├── fish-wsl.fish    # Fish shell WSL-specific config
│   └── zsh-wsl.zsh      # Zsh shell WSL-specific config
├── assets/              # Branding assets
│   ├── cachyos.svg      # Original logo (vector)
│   └── cachyos.ico      # Windows icon (multi-resolution)
├── scripts/             # Helper scripts
│   ├── setup-terminal.ps1     # Quick Windows Terminal setup
│   ├── Setup-WindowsTerminalProfile.ps1  # Advanced Terminal setup
│   └── override-manifest.ps1  # Local testing script
├── docs/                # Documentation
├── dist/                # Build output (gitignored)
│   ├── cachyos-v3-rootfs.tar.gz
│   └── cachyos-v3.wsl
└── Makefile             # Build automation

Contributing

This project was built as a learning exercise to understand WSL custom distribution creation. Contributions, suggestions, and feedback are welcome!

Development Workflow

Make changes to config files or build scripts
Rebuild rootfs: make clean && make rootfs
Test on Windows using the testing guide
Document any issues or improvements
Iterate

Release Process

Releases are automated using GitHub Actions. When you push a version tag, the workflow automatically builds, validates, and publishes the release.

Creating a New Release

Ensure your changes are committed and pushed:

git add .
git commit -m "Your changes"
git push

Create and push a version tag:
```
git tag v1.0.0
git push origin v1.0.0
```
GitHub Actions will automatically:
- Build the rootfs using Docker
- Run comprehensive validation checks
- Create the .wsl file
- Create a GitHub Release at https://github.com/dwalleck/cachyos-wsl/releases
- Upload cachyos-v3.wsl as a downloadable asset
- Generate release notes

Continuous Integration

Every push to main or develop branches triggers the build workflow, which:

Builds and validates the distribution
Runs static validation checks
Uploads build artifacts for testing

See .github/workflows/build.yml and .github/workflows/release.yml for workflow details.

Credits

CachyOS Team - For the excellent Arch-based distribution and optimizations
Microsoft - For WSL and comprehensive documentation
Arch Linux - For the solid foundation
Nord Theme - For the beautiful color palette used in Terminal

License

This project packages and configures existing open-source software:

CachyOS and Arch Linux packages are under their respective licenses
CachyOS branding used with reference to official sources
Build scripts and configuration files: MIT License (see below)

MIT License

MIT License

Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Links

Built with ❤️ as a learning project

For questions or issues, please open a GitHub issue.

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
.beads		.beads
.github/workflows		.github/workflows
assets		assets
build		build
config		config
docs		docs
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Makefile		Makefile
README.md		README.md
build-custom-distro.md		build-custom-distro.md
use-custom-distro.md		use-custom-distro.md

Folders and files

Latest commit

History

Repository files navigation

CachyOS for WSL

Features

Requirements

Quick Start

Option 1: Direct Installation (Recommended)

Option 2: Local Testing (Developers)

Post-Install Configuration

Windows Terminal Profile Setup

Building from Source

Prerequisites

Build Steps

First Run Experience

Package Management

Available Repositories

Shell Configuration

Fish (Default Shell)

Fish Features

Zsh (Alternative Shell)

Bash (Fallback Shell)

Shell Features Comparison

Fonts for Best Experience

Configuration

WSL Configuration

Distribution Configuration

Windows Terminal Integration

Troubleshooting

Package Signature Errors

OOBE Doesn't Run

systemd Issues

Documentation

Project Structure

Contributing

Development Workflow

Release Process

Creating a New Release

Continuous Integration

Credits

License

MIT License

Links

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages