Skip to content
Get packs

Guide · Open source

How to use Amethyst: install, set up and use tiling on Mac

Updated · written with AI from the project's own documentation and checked against our catalogue data

Amethyst is an open-source tiling window manager for macOS, inspired by xmonad. It automatically arranges your open windows into layouts so they fill the screen without overlapping, and it is controlled mostly with keyboard shortcuts. This guide covers installation, the required macOS permission and settings, the default shortcuts, and the main layouts, so you can start tiling your windows.

Amethystianyh/Amethyst · ★ 16.3k · MIT

Quick start

  1. 1Install the app. Install Amethyst with Homebrew Cask using brew install --cask amethyst, or download it from the releases page.
  2. 2Grant Accessibility access. Open Privacy & Security, then Privacy, then Accessibility, and allow Amethyst.
  3. 3Disable automatic Space rearranging. Turn off the Mission Control option, or run the defaults write command and restart the Dock with killall Dock.
  4. 4Learn the core shortcuts. Practice mod1 + space to cycle layouts, mod1 + j and k to move focus, and mod1 + enter to swap with the main window.
  5. 5Pick your layouts. Cycle through the layouts and enable only the ones you use, such as Tall, Wide or Column.

Install Amethyst on macOS

Amethyst is available for direct download from the project's releases page on GitHub, or through Homebrew Cask. The README notes that Amethyst currently only supports macOS 10.15 or later.

If you use Homebrew, install the cask from a terminal with the command below.

brew install --cask amethyst

Grant Accessibility permission

Amethyst needs permission to use the macOS accessibility APIs. Open the Privacy & Security tab, go to Privacy, then Accessibility, and allow Amethyst. Without this permission, Amethyst cannot arrange your windows.

Turn off automatic Space rearranging

The README recommends disabling the Mission Control setting "Automatically rearrange Spaces based on most recent use". It is on by default and makes your Spaces swap places based on use, which makes keyboard navigation between Spaces unpredictable.

You can change it in System Settings under Mission Control, or run the two commands below in a terminal. The second command restarts the Dock so the change takes effect.

defaults write com.apple.dock workspaces-auto-swoosh -bool NO killall Dock

Learn the default keyboard shortcuts

Amethyst defines two modifier combinations, mod1 and mod2, and can optionally use two more, mod3 and mod4. By default, mod1 is option + shift and mod2 is ctrl + option + shift. mod3 and mod4 are not defined by default.

Most commands are a mapping to xmonad key combinations. These are the most useful defaults to learn first:

  • mod1 + space: cycle layout forward; mod2 + space: cycle layout backwards
  • mod1 + j / k: move focus counter clockwise / clockwise
  • mod2 + j / k: swap focused window counter clockwise / clockwise
  • mod1 + h / l: shrink / expand the main pane
  • mod1 + enter: swap focused window with main window
  • mod1 + t: toggle float for focused window
  • mod2 + z: relaunch Amethyst
  • mod2 + left / right: throw focused window to the space on the left / right
  • mod1 + w / e / r: focus Screen 1 / 2 / 3

Choose a layout

Amethyst lets you cycle among several layouts, and you can enable or disable layouts to control which ones appear in the cycle. The default is Tall: one main pane on the left, with the other windows in a pane on the right. Other layouts include:

  • Tall-Right: Tall with the main pane on the right
  • Wide: the main pane is on top and the other pane on the bottom
  • Two Pane: one visible window at a time in the secondary pane, adapting to screen orientation
  • 3Column-Left, 3Column-Middle and 3Column-Right: three columns
  • Widescreen-Tall: useful on very wide screens
  • Fullscreen: the focused window fills the screen
  • Column and Row: one column or row per window
  • Floating: windows can be moved and resized freely

Use the floating mode when needed

Amethyst does not force every window into a tile. You can toggle a single window with mod1 + t, or toggle global tiling with mod2 + t. The README describes Floating as a mode where all windows can be moved and resized. For troubleshooting, the README points to docs/troubleshooting.md.

What people use it for

  • Keeping a code editor, browser and terminal side by side without overlapping windows
  • Moving windows between Spaces with mod2 + left or mod2 + right
  • Switching focus across multiple external screens with mod1 + w, e, r
  • Using a wide monitor with Widescreen-Tall or 3Column layouts

Frequently asked questions

Is Amethyst free?

Amethyst is open source under the MIT licence, according to its README. The source is on GitHub and the project is available for direct download or through Homebrew Cask.

What macOS version do I need for Amethyst?

The README says Amethyst is only supported on macOS 10.15 or later. Older macOS versions are not supported.

How do I install Amethyst with Homebrew?

Run brew install --cask amethyst in a terminal. You can also download the app directly from the project's releases page on GitHub.

Why are my Spaces switching places in Amethyst?

macOS enables Automatically rearrange Spaces based on most recent use by default, which swaps Spaces around. The README recommends disabling it, either in Mission Control or with the defaults write command followed by killall Dock.

Why isn't Amethyst moving my windows?

Amethyst needs Accessibility permission under Privacy & Security, then Privacy, then Accessibility. The README also links to a troubleshooting page for common issues.

How does Amethyst compare to Rectangle, yabai or Magnet?

Amethyst is inspired by xmonad and automatically tiles windows with keyboard shortcuts. Other tools in the same space include Rectangle, yabai, Magnet and Divvy, which take different approaches; this guide does not benchmark them.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Amethyst suits Mac users who regularly work with several windows side by side, prefer the keyboard, or already like xmonad. It is a poor fit if you prefer placing windows by hand or want a mouse-driven workflow, since layouts are applied automatically and the README centers on shortcuts. If you need a simpler snap-to-edge tool, consider Rectangle, Magnet or Divvy.

Install options & downloads