Emoji Kbd

Fast and efficient emoji picker with keyboard-driven navigation. Available as GUI and TUI.

🚀 Features

Packed with 3940 emojis 🤩 including 2030 variants (skin tones, gender, …) and 5249 symbols Α-Ω in 35 groups ⯒.
Fast keyboard ⌨️ and mouse 🖱️ navigation.
Combined favorites ⭐️ and recent ⟲ list.
Powerful search 🔎.
Grouping of people emojis differing just by gender 🎅🤶🧑‍🎄.
TUI/Terminal 📟️ version available.
Localization 🏳️‍🌈 where available.
Customizable keyboard layouts (US, DE, Bone Corne, …).
Cross-platform: Linux (Wayland/Hyprland), Windows, …

🖼️ Screenshots

GUI:

emoji-kbd-gui-0.1.0.mp4

TUI:

emoji-kbd-term-0.1.0.mp4

🎯 Why Choose Emoji Kbd?

Speed and efficiency. Get any favorite emoji in just 3 keystrokes:

Win-. — Open Emoji Kbd
key — Select emoji (each emoji has a keyboard key assigned)
Enter — Insert and close

No mouse needed. No scrolling through categories. Just fast keyboard navigation.

📦 Quick Start

# Clone and setup
git clone https://github.com/robertwidfen/emoji-kbd
cd emoji-kbd
python -m venv .venv
source .venv/bin/activate
pip install -e . # or uv sync

# Test run
python src/guikbd.py

Linux (Arch/Hyprland):

# Install dependencies
sudo pacman -S python openbsd-netcat wl-clipboard wtype kitty noto-fonts-emoji

Hyprland < 0.55 - add key binding to ~/.config/hypr/bindings.conf:

unbind = SUPER, period 
bindd = SUPER, period, Emojis, exec, /PATH_TO/scripts/emoji-kbd-gui-wl
#bindd = SUPER, period, Emojis, exec, /PATH_TO/scripts/emoji-kbd-kitty-hl-open

Hyprland >= 0.55 - add key binding to ~/.config/hypr/bindings.lua:

hl.unbind("SUPER + period")
hl.bind(
    "SUPER + period",
    hl.dsp.exec_cmd("/PATH_TO/scripts/emoji-kbd-kitty-hl-open"),
    { description = "Emojis" }
)

Windows (11):

Run with AutoHotkey (overrides Win-.)

scripts\emoji-kbd.ahk

See Installation for detailed platform-specific setup.

👆 UI

Top left is the emoji input field and on the right the search field.

In the middle is a (key)board like overview of emoji groups resp. emojis. Each one has a key associated with it that opens the group or inserts the emoji into the input field.

At the bottom is a status field showing information about the currently selected emoji.

Enter in the input field will copy the content of the input field to the clipboard and and inserts it into your app.

If your window manager supports it, a left click in left half of status allows for moving the window and in right half allows for resizing.

🔑 Key bindings

Key 🖮	Action
Global
`Cursor`, `Home`, `End`	navigate around
`Ctrl-I`	focus input
`Ctrl-F`	focus search
`PageUp`/`PageDown`	scroll page up/down
`Esc`	back to previous board
> Input and 🔎 Search
`Down`	focus board
`Tab`	focus board and keep focus
> Input
key on board	select and insert emoji
`Enter`	close and insert/print result
`Right` at end	focus search
🔎 Search
`Enter`	insert first match
`Right` at end	select next match
`Left` at start	focus input
⌨️ Board
key on board	select and insert emoji
`Space` + key on board	open variants
`Enter`	insert selected emoji
`Up` in first row	focus input
⟲ Recent Board additional keys
`Shift-Left`/`Right`	move selected left/right
`Shift-Enter`	toggles favorite state
`Space` + key on board	toggles favorite state
`Shift-Delete`	delete selected
🖱️ Mouse
`LeftClick`	insert emoji
`LeftClick` in upper right corner	open variants
`DoubleLeftClick`	insert emoji and close
`RightClick`	back to previous board
`Wheel`	scroll pages

⟲ Recent List

Inserted emojis will be put to the recent list.

Items will be added without variants (skin tone, gender, …).

Every item has a score and items are sorted by score when new ones are added.

A score ≥ 100 makes an item a favorite and it will not change its score or position anymore.

When an item is inserted into the input its score will increase by 10 and the score of all others - except favorites - decreases by 1.

🔎 Search

Enter the search field and type to filter emojis. Results are sorted by relevance score. Search terms are separated by space.

Empty search displays all available emojis.

Search patterns:

Pattern	Example	Matches
Plain text	`heart`	♥️💟😻💗🫀💓💔😍…
`#tag`	`#love`	🤟😘🏩🥰😍😗😙😻…
`group,subgroup`	`smileys,tongue`	😋😛😜🤪😝🤑
`,subgroup`	`,mammal`	🐵🐒🦍🦧🐶🐕️…
`+hexcode`	`+221e`	∞

🛠️ Requirements

Core:

Python 3.12+
Noto Color Emoji font (auto-downloaded on first run)

Platform-specific:

Platform	Dependencies
Linux (Hyprland)	`nc`, `wl-copy`, `wtype`, `kitty`, `noto-fonts-emoji`
Windows	AutoHotkey v2

Required Python packages are installed automatically with pip install -e .

Data sources which will be automatically downloaded:

Emoji data: Emojibase (MIT License)
Unicode data: UnicodeData (Unicode License)

🔨 Installation

Choose your platform and follow the integration steps:

💧 Linux (Hyprland)

Install dependencies - in Arch by:

sudo pacman -S openbsd-netcat wl-clipboard wtype kitty noto-fonts-emoji

Add hotkey to ~/.config/hypr/bindings.conf:

unbind = SUPER, period

# Option 1: TUI if you have kitty installed
bindd = SUPER, period, Emojis, exec, /PATH_TO/scripts/emoji-kbd-kitty-hl-open

# Option 2: GUI
# bindd = SUPER, period, Emojis, exec, /PATH_TO/scripts/emoji-kbd-gui-wl

Add window rules for fast opening (noanim) and floating window to ~/.config/hypr/hyprland.conf:

Hyprland ≥ 0.53:

windowrule {
    name = Emoji Kbd
    match:title = ^(Emoji Kbd)$
    tag = -floating-window
    tag = -terminal
    no_anim = on
    float = on
    center = on
    max_size = 800 600
    min_size = 500 200
}

Hyprland ≤ 0.52:

windowrulev2 = tag -floating-window, title:^Emoji Kbd$
windowrulev2 = tag -terminal, title:^Emoji Kbd$
windowrulev2 = noanim, title:^Emoji Kbd$
windowrulev2 = float, title:^Emoji Kbd$
windowrulev2 = center, title:^Emoji Kbd$
windowrulev2 = unset size, title:^Emoji Kbd$
windowrulev2 = size 600 285, title:^Emoji Kbd$

Optionally copy res/emoji-kbd.desktop to ~/.local/share/applications/ for a launcher entry and adjust the paths in the copied file.

🪟 Windows

Setup:

Install AutoHotkey v2
(Optional) Install Windows-compatible Noto Color Emoji font
- If you already have Noto Color Emoji, replace it with the Windows-compatible version to avoid slow flag rendering
Run scripts\emoji-kbd.ahk (double-click or add to startup)

Default hotkey: Win-. (overrides Windows emoji picker)

To change the hotkey, edit scripts/emoji-kbd.ahk and modify the #.:: line.

First startup note: Initial launch downloads emoji databases and Noto font. You might see a daemon startup warning. Check logs if issues persist.

📟 Terminal

Terminal compatibility:

Terminal	Emoji Support	Notes
Kitty	✅ Full	Perfect rendering, all flags and graphemes
Ghostty	⚠️ Mostly	Minor rendering issues
Alacritty	❌ Limited	Misaligned columns, monochrome emojis
Others	❓	Font configuration needed for Noto Color Emoji

⚙️ Customization

See res/emoji-kbd.toml for all available options.

Copy res/emoji-kbd.toml or parts to ~/.config/emoji-kbd/emoji-kbd.toml and edit it.

For example, change the locale and layout (case-sensitive) as follows:

[board]
locale = "de"
layout = "DE"

Add own layout:

[[layout]]
…

For everything else - change the code 😉.

🔍 Troubleshooting

Issue: Emojis not displaying, monochrome, flags show as 🇦 🇧 🇨, …

Cause: Missing or old Noto Color Emoji font.
Fix Linux: sudo pacman -S noto-fonts-emoji (Arch) or equivalent.
Fix Windows: Download Windows-compatible Noto Color Emoji.
Fix Terminal: Configure font fallback (fontconf, …) to use Noto font.

Issue: TUI misalignment

Cause: Terminal doesn't handle complex graphemes.
Fix: Use Kitty terminal (recommended) or switch to GUI.

Issue: Slow first startup

Expected: First run downloads ~5 MB of emoji data and Noto font on Windows. May cause startup warning on Windows.
Fix: Wait 30-60 seconds for downloads to complete.
Subsequent runs: Uses cache (~ms startup).

Issue: Win-. not working (Windows)

Check: AutoHotkey script is running (scripts\emoji-kbd.ahk)
Check: No other app is overriding Win-.

Emojis from news Unicode standard are missing

Clear cache to update emojis: From the ⚙️ menu select ♻️ and restart.
Update Noto font.

📁 File Locations

Path	Purpose
`~/.config/emoji-kbd/emoji-kbd.toml`	User configuration
`~/.local/state/emoji-kbd/recent.txt`	Recent/favorite emojis list
`~/.local/state/emoji-kbd/*.log`	Log files
`~/.cache/emoji-kbd/*`	Emoji databases, caches, Noto font

Development

When the environment variable EMOJI_KBD_DEV is set to a value the config file is taken from res/emoji-kbd.toml and all other files go to .local in the repo. It can be set also to a comma separated list of words, currently only "no_cache", to disable use of cache.

Run terminal version for testing:

python src/termkbd.py

Run kitty helper script:

./scripts/emoji-kbd-kitty-hl-open

GUI daemon: Daemon mode keeps the app loaded in memory for instant opening. Communicates by socket. If not reachable starts a new daemon.

python src/guidmn.py get    # Wait for result
python src/guidmn.py show   # Show only

Check emoji grouping:

python src/emojis.py

Check and query config:

python src/config.py
python src/config.py board.layout

🔄 Comparison with Alternatives

Feature	Emoji Kbd	Others
Keyboard first	✅	❌
Favorites ⭐	✅	❌
Advanced Grouping ⯒	✅	❌
Advanced Search 🔎	✅	❌ Often just name
Cross Platform	✅	❌ Often just one

Why Emoji Kbd?

Keyboard-first design - navigate fast without mouse
Favorites for fast access by muscle memory
Large recent list with smart scoring
Advanced search by name, tags, (sub)groups, code
Gender variant grouping (🎅🤶🧑‍🎄)
See meta data code, name, group, subgroup, tags
Cross-platform Linux + Windows + …

Origin story: I disliked the new picker from Windows 11 as it had a much smaller recent list than the Windows 10 version. Looking for alternatives I found https://github.com/gilleswaeber/emoji-keyboard from Gilles Weber and added the recent emojis board and was very happy with it for years.

But when switching back to Linux for the desktop I could not find a proper alternative and thus made my own one - Emoji Kbd - inspired by emoji-keyboard.

🚧 Roadmap

Kaomoji and GIFs will never be added. 😉

⚖️ Licenses

Emoji Kbd: GPL-3.0-or-later
Emojibase: Copyright (c) Miles Johnson. License: MIT License.

Name		Name	Last commit message	Last commit date
.local		.local
.vscode		.vscode
res		res
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository navigation

About

Repository files navigation

Emoji Kbd

🚀 Features

🖼️ Screenshots

🎯 Why Choose Emoji Kbd?

📦 Quick Start

👆 UI

🔑 Key bindings

⟲ Recent List

🔎 Search

🛠️ Requirements

🔨 Installation

💧 Linux (Hyprland)

🪟 Windows

📟 Terminal

⚙️ Customization

🔍 Troubleshooting

📁 File Locations

Development

🔄 Comparison with Alternatives

🚧 Roadmap

⚖️ Licenses

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Emoji Kbd

🚀 Features

🖼️ Screenshots

🎯 Why Choose Emoji Kbd?

📦 Quick Start

👆 UI

🔑 Key bindings

⟲ Recent List

🔎 Search

🛠️ Requirements

🔨 Installation

💧 Linux (Hyprland)

🪟 Windows

📟 Terminal

⚙️ Customization

🔍 Troubleshooting

📁 File Locations

Development

🔄 Comparison with Alternatives

🚧 Roadmap

⚖️ Licenses

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages