Write the code. Change the world.
development

Arch Linux + Hyprland에서 한글 키보드 입력 설정하기

· Kyoungwon Lee

Omarchy를 통해 Arch Linux를 접하게 됐고, 조금씩 적응해가는 시간을 보내고 있어요. 적응 과정 중에서 꼭 필요했던 한글 키보드 레이아웃을 설정하고 자연스럽게 한글 입력까지 가능한 환경을 만들기 위한 과정을 정리했어요. 단순히 us,ko 키보드 전환뿐 아니라, fcitx5를 활용한 완전한 한글 조합 입력(예: “ㅎㅏㄴㄱㅡㄹ” → “한글”)까지 다루고 있어요.

1. Hyprland에서 한글 키보드 레이아웃 설정하기

Hyprland에서는 ~/.config/hypr/hyprland.conf 파일의 input 블럭에서 키보드 레이아웃을 설정할 수 있어요. Omarchy의 경우 기본적으로 en과 de가 써있고 주석처리 되어 있는데 아래와 같이 변경하면 돼요.

input {
  kb_layout = us,kr
  kb_options = compose:caps,grp:alt_space_toggle
}
  • us: 기본 영어 레이아웃
  • kr: 한글 키보드 레이아웃 (ko 대신 kr을 사용하는 게 더 호환성이 좋아요)
  • compose:caps,grp:alt_space_toggle: Alt + Space로 레이아웃 전환

💡 문제 해결 팁:
만약 invalid keyboard layout passed 오류가 발생한다면 kr로 변경하거나 다음 패키지를 설치해보세요:

sudo pacman -S xkeyboard-config

2. Fcitx5 한글 입력기 설치 및 설정

단순한 레이아웃 전환만으로는 조합형 한글 입력이 되지 않아요. 자연스러운 한글 입력을 위해 fcitx5 입력기를 설정해줘야 해요.

2.1 fcitx5 패키지 설치

sudo pacman -S fcitx5 fcitx5-hangul fcitx5-configtool
  • fcitx5: 메인 입력기 프레임워크
  • fcitx5-hangul: 한글 입력 지원
  • fcitx5-configtool: 설정 GUI

2.2 환경 변수 설정

~/.config/hypr/environment.conf 파일을 열고 아래 내용을 추가해요:

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

2.3 자동 실행 설정

Hyprland 설정에 다음을 추가해요:

exec-once = fcitx5 &

3. Fcitx5 입력기 구성

GUI 툴로 입력기를 설정할 수 있어요:

fcitx5-configtool
  • Hangul 입력기를 추가해요.
  • 한/영 전환 단축키는 보통 Shift + Space로 설정해요.
  • 입력기 순서를 Hangul → Keyboard - English (US)로 정렬해요.

4. 테스트 및 확인

  • Alt + Space → Hyprland 키보드 레이아웃 전환 (us ↔ kr)
  • Shift + Space → Fcitx5 한영 전환
  • 현재 레이아웃 확인:
setxkbmap -query

5. 보너스: Wayland용 클립보드 도구 설치

Wayland 환경에서 클립보드 기능을 제대로 활용하려면 다음 패키지를 설치하면 좋아요:

sudo pacman -S wl-clipboard
  • 클립보드 붙여넣기: wl-paste
  • 클립보드 복사: wl-copy

마무리

이 설정을 완료하면 Arch Linux + Hyprland 환경에서도 안정적으로 한글 입력을 할 수 있어요.
Hyprland의 키보드 전환과 Fcitx5의 한글 입력을 함께 사용하면 매우 유연한 환경이 만들어져요.

아직은 익숙하지 않은 환경이라 하루에 30분 정도만 사용해보면서 필요한 환경을 만들고 있는데, 익숙해지기만 한다면 마음속에 꿈꿔왔던 애플 맥으로부터의 탈출을 시도해볼 수 있지 않을까하는 기대를 가지고 있어요. 지금은 홈랩 장비로 쓰다가 방치하고 있던 구형 데스크탑을 사용하고 있어서, 블루투스도 안되는 열악한 환경이지만 잘 적응하면 좋은 장비를 구매하는 핑계로 삼아봐야겠어요.😁

LLM(Claude Code 등)에게 맡기기

이 글은 2025년 7월에 직접 손으로 하나씩 설정하던 과정을 정리한 거예요. 지금은 Claude Code 같은 코딩 에이전트가 내 컴퓨터에서 위 단계를 대신 실행해줄 수 있어요. Hyprland 0.55부터는 설정 파일이 Lua(hyprland.lua)로 바뀌어서 위 예시와 형식이 다를 수 있는데, 프롬프트에 지금 쓰는 형식을 확인하고 거기에 맞춰 적용하라고 적어 뒀어요. 아래 프롬프트를 복사해서 에이전트에 붙여넣으면 돼요.

💡 실행 위치 팁:
Hyprland가 설치된 컴퓨터에서 바로 에이전트를 실행해도 되고, 아직 한글 입력이 안 돼서 불편하다면 그 컴퓨터에 SSH를 켜 두고 다른 컴퓨터에서 접속한 뒤 SSH 세션 안에서 Claude Code 같은 에이전트를 실행해도 돼요.

Arch Linux + Hyprland 환경에서 한글 입력(fcitx5 + fcitx5-hangul)을 설정해줘. 아래 순서와 규칙을 꼭 지켜줘.

1. 먼저 환경을 확인하고, 아무것도 바꾸기 전에 확인한 내용을 보고해줘.
   - Arch Linux인지, Omarchy인지 (/etc/os-release, ~/.local/share/omarchy 또는 /usr/share/omarchy 존재 여부)
   - Hyprland 버전 (hyprctl version)
   - 설정 형식: ~/.config/hypr/hyprland.lua 가 있으면 Lua 설정(0.55 이후)이 로드되고, 없으면 hyprland.conf(hyprlang)가 로드돼. 실제로 로드되는 파일과 그 파일이 불러오는(require / source) 사용자 설정 파일을 확인해줘. (Omarchy는 input, envs, autostart 같은 파일로 나뉘어 있을 수 있음)
   - 이미 설치된 입력기 (pacman -Q 로 fcitx5, ibus, kime 등 확인)와 fcitx5 가 이미 서비스나 자동 실행으로 떠 있는지
   - 현재 kb_layout / kb_options 등 입력 설정과 입력기 환경 변수 설정 상태

2. 파일을 수정하기 전에 반드시 백업해줘.
   - ~/.config/hypr/ 와 ~/.config/fcitx5/ 전체를 타임스탬프가 붙은 백업 디렉터리(예: ~/.config/backup-hangul-YYYYMMDD-HHMMSS/)에 복사하고, 백업 경로를 알려줘.

3. 아래 설정을 적용해줘. 값은 이 글 본문과 같지만, 문법은 1번에서 확인한 형식을 따라줘. 이미 되어 있는 단계는 건너뛰고, 같은 줄을 중복으로 추가하지 말고, 필요한 부분만 최소한으로 수정해줘. 수정은 ~/.config/hypr/ 와 ~/.config/fcitx5/ 의 사용자 설정 파일에만 하고, 업데이트 때 덮어써지는 Omarchy 기본 파일(~/.local/share/omarchy/, /usr/share/omarchy/)은 건드리지 말아줘.
   - 키보드: kb_layout = us,kr, kb_options = compose:caps,grp:alt_space_toggle (Alt+Space로 레이아웃 전환). 기존에 다른 레이아웃이나 옵션(예: us,de, caps:escape)이 있으면 지우지 말고 kr 만 추가하고, kb_options 는 관련된 grp:, compose: 항목만 바꾸고 나머지는 그대로 둬줘. Lua면 hl.config({ input = { ... } }), hyprlang이면 input 블럭에 넣어줘.
   - 패키지: fcitx5, fcitx5-hangul, fcitx5-configtool 설치. GTK 앱에서도 한글이 입력되도록 fcitx5-gtk 가 없으면 같이 설치해줘.
   - 환경 변수: GTK_IM_MODULE=fcitx, QT_IM_MODULE=fcitx, XMODIFIERS=@im=fcitx, INPUT_METHOD=fcitx. Lua면 hl.env("KEY", "VALUE"), hyprlang이면 env = KEY,VALUE 형식으로, 실제로 로드되는 파일에 넣어줘. (uwsm 을 쓰면 ~/.config/uwsm/env 에 export KEY=VALUE 형식)
   - 자동 실행: fcitx5 가 이미 서비스나 다른 자동 실행으로 뜨고 있으면 추가하지 말아줘. 없으면 Lua는 그 설정에서 쓰는 자동 실행 방식(예: Omarchy autostart 헬퍼, hl.on("hyprland.start", ...))으로, hyprlang은 exec-once = fcitx5 로 추가해줘.
   - 입력기: fcitx5 에 Hangul 추가. 순서는 Hangul → Keyboard - English (US), 한/영 전환은 Shift+Space. fcitx5-configtool로 하거나, (SSH 접속처럼 화면이 없어서 GUI를 쓸 수 없으면) fcitx5를 종료한 뒤 ~/.config/fcitx5/profile 을 직접 수정해줘. 이때 입력기 Name 은 hangul, keyboard-us 를 쓰고, 한/영 전환 키는 ~/.config/fcitx5/config 의 [Hotkey/TriggerKeys] 에 설정해줘.

4. sudo 가 필요한 명령이나 패키지 설치 명령은 실행하기 전에 정확한 명령어를 먼저 보여주고 내가 명시적으로 승인할 때까지 기다려줘. 승인 없이 sudo 를 실행하면 안 돼.

5. 끝나면 아래 내용을 정리해서 보고해줘.
   - 변경하거나 새로 만든 파일 목록
   - 되돌리는 방법 (백업에서 복원하는 방법, 제거할 패키지)
   - 재로그인이 필요한지, 아니면 hyprctl reload 나 fcitx5 재시작으로 충분한지

에이전트가 시스템 설정 파일을 직접 수정하니까 승인 전에 명령어를 꼭 확인하고, 끝난 뒤에는 결과도 직접 점검해보세요. 백업 경로는 복구할 때 필요하니 따로 기록해두는 게 좋아요.

#archlinux#hyprland#keyboard#fcitx5#wayland#한글#입력기