Omarchy Field Guide: From macOS to Arch + Hyprland in 12 Chapters

Omarchy: an AI-friendly, ready-to-use god-tier Linux distribution

Version: Omarchy 4.x (includes content from the stable 3.x line)

Intended readers: developers migrating from Windows/macOS; users who want Arch’s power but are tired of DIY configuration; keyboard-driven workflow enthusiasts; and beginners to tiling window managers

Table of Contents

1. Preface
2. Chapter 1: What Is Omarchy? DHH and 37signals’ Linux Manifesto
3. Chapter 2: Core Advantages in Depth
4. Chapter 3: Installation: From Zero to the First Screen
5. Chapter 4: First Use and Basic Interaction
6. Chapter 5: The Complete Keyboard Shortcut Guide
7. Chapter 6: Common Configuration Explained
8. Chapter 7: Installing Common Software and Usage Tips
9. Chapter 8: Advanced Screenshots and Screen Recording
10. Chapter 9: The Complete Guide to the Built-in AI Agent
11. Chapter 10: System Maintenance and Update Management
12. Chapter 11: Cross-Platform Migration Guide
13. Chapter 12: Advanced Customization and Troubleshooting
14. Conclusion
15. Appendix A: Omarchy CLI Command Quick Reference
16. Appendix B: FAQ
17. Chapter 13: The Real World: Reviews, Ecosystem, and More Tips

Throughout the long history of personal computing, operating systems have swung between two extremes. At one end is radical freedom—“you can do anything, but you need to decide how”—embodied by Arch Linux. It gives you the purest base and the most complete control, but the price is hours or even weekends spent configuring, debugging, and tweaking. At the other end is radical convenience—“everything has been arranged for you”—embodied by macOS, Windows, and countless desktop Linux distributions. They work out of the box, but they often come with bloated default software, rigid workflows, and the stubborn attitude of “this isn’t right for you, but this is how we do it.”

Few have truly walked the middle path. Then, in 2025, David Heinemeier Hansson—the creator of Ruby on Rails and co-founder of 37signals (the company behind Basecamp and HEY), better known to most of us as DHH—launched Omarchy.

Omarchy calls itself “a beautiful, modern, opinionated Linux distribution.” It is based on Arch Linux, pairs it with the Hyprland tiling window manager, and takes its core philosophy from omakase (おまかせ)—the Japanese dining custom in which the choice of ingredients is left entirely to a trusted chef. DHH and his team make the decisions about software selection, interface design, and interaction logic on your behalf, sparing you the pain of setting up a development environment from scratch. The result is a polished, efficient, keyboard-driven workstation, ready out of the box.

This book is not a brief introduction to Omarchy; it is a full-field practical manual prepared for you. Whether you’re installing Omarchy for the first time or already using it and want to dig into every feature; whether you just need to quickly configure Chinese input and a proxy, or want to thoroughly understand how the built-in AI agent works, customize themes, or master advanced screen capture and recording techniques—this book covers it all.

The book has twelve chapters plus two appendices, designed so that every step is actionable, every command can be copied directly, and every choice has a rationale. We don’t just tell you “which key to press”; we tell you “why this key,” “what to do if you press the wrong one,” and “can you change it to something else.”

Before learning Omarchy, prepare yourself for a mindset shift: everything here is keyboard-centered. This isn’t an arbitrary challenge for newcomers; it’s a return to a proven, efficient way of working—just as programmers write code in Vim instead of clicking menus with a mouse. At first it may feel awkward, and you may even miss the days of clicking menus. But once you’ve memorized your first set of shortcuts and realize you no longer have to get up for coffee and come back to grab the mouse, you’ll understand that this “mouseless” life is not a step backward—it’s a leap in productivity.

Welcome to Omarchy. Let’s get started.

Chapter 1: What Is Omarchy? DHH and 37signals’ Linux Manifesto

1.1 A Story About Being Opinionated

Most Linux distributions are philosophically “neutral.” Ubuntu doesn’t tell you which terminal to use; Fedora doesn’t force a particular editor on you; even the relatively fixed openSUSE Tumbleweed confronts you with a long list of optional components during installation. Neutrality seems fair, but it isn’t—it simply drops the burden of choice on every new user: what to install, what not to install, how to configure it, which font looks good, which wallpaper feels clean?

For hardcore geeks, this is a feast; for developers who just want to focus on their work, it often becomes an exhausting war of attrition.