Korean Input on Arch Linux + Hyprland with Fcitx5

I discovered Arch Linux through Omarchy, and I’ve been spending time getting used to it little by little. This post walks through how I set up a Korean keyboard layout—something I absolutely needed during that process—and built an environment where Korean input feels natural. It covers not only simple us,ko keyboard switching, but also full Korean composition with fcitx5 (e.g. “ㅎㅏㄴㄱㅡㄹ” → “한글”).

1. Setting Up the Korean Keyboard Layout in Hyprland

In Hyprland, you can configure the keyboard layout in the input block of ~/.config/hypr/hyprland.conf. In Omarchy, en and de are listed by default and commented out; change them as shown below.

input {
  kb_layout = us,kr
  kb_options = compose:caps,grp:alt_space_toggle
}

us: Default English layout
kr: Korean keyboard layout (kr has better compatibility than ko)
compose:caps,grp:alt_space_toggle: Switch layouts with Alt + Space

💡 Troubleshooting tip:
If you get an invalid keyboard layout passed error, try changing it to kr or installing the following package:

sudo pacman -S xkeyboard-config

2. Installing and Configuring the Fcitx5 Korean Input Method

Switching layouts alone doesn’t enable compositional Korean input. To type Korean naturally, you need to set up the fcitx5 input method.

2.1 Install the fcitx5 packages

sudo pacman -S fcitx5 fcitx5-hangul fcitx5-configtool

fcitx5: Main input method framework
fcitx5-hangul: Korean input support
fcitx5-configtool: Configuration GUI

2.2 Set environment variables

Open ~/.config/hypr/environment.conf and add the following:

export GTK_IM_MODULE=fcitx
export QT_IM_MODULE=fcitx
export XMODIFIERS=@im=fcitx
export INPUT_METHOD=fcitx

2.3 Configure autostart

Add the following to your Hyprland configuration:

exec-once = fcitx5 &

3. Configuring Fcitx5 Input Methods

You can configure input methods with the GUI tool:

fcitx5-configtool

Add the Hangul input method.
The Korean/English toggle shortcut is usually set to Shift + Space.
Arrange the input methods in this order: Hangul → Keyboard - English (US).

4. Testing and Verification

Alt + Space → Switch the Hyprland keyboard layout (us ↔ kr)
Shift + Space → Toggle Korean/English in Fcitx5
Check the current layout:

setxkbmap -query

5. Bonus: Installing a Clipboard Tool for Wayland

To make full use of clipboard features in Wayland, it’s a good idea to install the following package:

sudo pacman -S wl-clipboard

Paste from the clipboard: wl-paste
Copy to the clipboard: wl-copy

Wrapping Up

With this setup complete, you can type Korean reliably on Arch Linux + Hyprland.
Combining Hyprland’s keyboard switching with Fcitx5’s Korean input creates a very flexible environment.

I’m still not used to this environment, so I’ve been using it for only about 30 minutes a day while setting up what I need. Once I get comfortable, I hope I can finally attempt the escape from Apple Mac that I’ve been dreaming of. Right now I’m using an old desktop that had been sitting unused after serving as home lab equipment. It’s a pretty rough setup—even Bluetooth doesn’t work—but if I adapt well, I might use that as an excuse to buy some nice hardware.😁

Handing It Off to an LLM (Claude Code, etc.)

This post documents the process I went through in July 2025, configuring everything by hand one step at a time. These days, a coding agent like Claude Code can carry out the steps above on my computer for me. Starting with Hyprland 0.55, the configuration file uses Lua (hyprland.lua), so the format may differ from the examples above. I’ve included instructions in the prompt to check which format you’re currently using and apply the settings accordingly. Just copy the prompt below and paste it into your agent.

💡 Tip for where to run it:
You can run the agent directly on the computer with Hyprland installed. If Korean input isn’t working yet and that’s inconvenient, you can enable SSH on that computer, connect from another computer, and run an agent such as Claude Code inside the SSH session.

Set up Korean input (fcitx5 + fcitx5-hangul) on Arch Linux + Hyprland. Be sure to follow the steps and rules below.

1. First, inspect the environment and report what you find before changing anything.
   - Whether the system is Arch Linux or Omarchy (check /etc/os-release and whether ~/.local/share/omarchy or /usr/share/omarchy exists)
   - Hyprland version (hyprctl version)
   - Configuration format: If ~/.config/hypr/hyprland.lua exists, the Lua configuration (0.55 and later) is loaded; otherwise, hyprland.conf (hyprlang) is loaded. Identify the file that is actually loaded and any user configuration files it includes (require / source). (Omarchy may split these into files such as input, envs, and autostart.)
   - Input methods already installed (check for fcitx5, ibus, kime, etc. with pacman -Q), and whether fcitx5 is already running as a service or through autostart
   - Current input settings such as kb_layout / kb_options, and the state of input-method environment variables

2. Always back up files before modifying them.
   - Copy all of ~/.config/hypr/ and ~/.config/fcitx5/ to a timestamped backup directory (e.g. ~/.config/backup-hangul-YYYYMMDD-HHMMSS/), and tell me the backup path.

3. Apply the settings below. The values are the same as in the body of this post, but follow the syntax of the format you identified in step 1. Skip steps that are already done, don't add duplicate lines, and make only the minimal necessary edits. Modify only user configuration files under ~/.config/hypr/ and ~/.config/fcitx5/; do not touch Omarchy default files (~/.local/share/omarchy/, /usr/share/omarchy/) that get overwritten during updates.
   - Keyboard: kb_layout = us,kr, kb_options = compose:caps,grp:alt_space_toggle (switch layouts with Alt+Space). If other layouts or options are already present (e.g. us,de, caps:escape), don't remove them; add only kr. For kb_options, change only the relevant grp: and compose: entries and leave the rest unchanged. For Lua, put this in hl.config({ input = { ... } }); for hyprlang, put it in an input block.
   - Packages: Install fcitx5, fcitx5-hangul, and fcitx5-configtool. If fcitx5-gtk is not installed, install it as well so that Korean input works in GTK apps.
   - Environment variables: GTK_IM_MODULE=fcitx, QT_IM_MODULE=fcitx, XMODIFIERS=@im=fcitx, INPUT_METHOD=fcitx. For Lua, use hl.env("KEY", "VALUE"); for hyprlang, use env = KEY,VALUE, and add them to the file that is actually loaded. (If using uwsm, use the export KEY=VALUE format in ~/.config/uwsm/env.)
   - Autostart: Do not add fcitx5 if it is already launched by a service or another autostart mechanism. Otherwise, for Lua, use the autostart method used by that configuration (e.g. Omarchy autostart helper, hl.on("hyprland.start", ...)); for hyprlang, add exec-once = fcitx5.
   - Input method: Add Hangul to fcitx5. Set the order to Hangul → Keyboard - English (US), and toggle Korean/English with Shift+Space. Use fcitx5-configtool, or (if you can't use the GUI because there is no display, as with an SSH session) quit fcitx5 and then directly edit ~/.config/fcitx5/profile. In that case, use hangul and keyboard-us as the input method Name values, and set the Korean/English toggle key in [Hotkey/TriggerKeys] in ~/.config/fcitx5/config.

4. For any command that requires sudo or installs packages, show me the exact command before running it and wait until I explicitly approve. Never run sudo without approval.

5. When finished, report the following:
   - Files changed or created
   - How to roll back (how to restore from the backup, packages to remove)
   - Whether a relogin is required, or whether hyprctl reload or restarting fcitx5 is sufficient

Because the agent directly modifies system configuration files, be sure to review the commands before approving them, and inspect the results yourself when it’s done. It’s a good idea to record the backup path separately, since you’ll need it for recovery.