Skip to main content

Emoji searcher for use with fzf

Project description

Code style: black GitHub Workflow Status PyPI version PyPI pyversions License: MIT


Small utility for manipulating emojis via fzf's --preview hook!


  1. Install fzf if you don't have it already to use its preview browser:

  2. Install the latest release of emoji-fzf from pypi:

    pip install emoji-fzf

See emoji-fzf --help for supported commands.

This project allows you to install the tool in an isolated environment:

zsh plugin

There's an excellent zsh plugin available, see here (thanks @pschmitt !):


Shell alias

You could add a shell alias like the following to your shell init script:

# if you aren't installing to a virtual env, you may need to add this to path
# (if it wasn't already) to access the tool from a pip installation
export PATH=$PATH:~/.local/bin

# add me to your ~/.bashrc or ~/.zshrc or whatnot
alias emoj="emoji-fzf preview | fzf -m --preview "emoji-fzf get --name {1}" | cut -d " " -f 1 | emoji-fzf get"
# to copy to xclip system keyboard (on mac use pbcopy) after selecting
emoj | xclip -selection c


You can also add the following to a ~/.vimrc file (apologies for the kludgy vimscript, I'm not great at it), to enable C-e to open the emoji picker and insert the selected emoji:

" Use emoji-fzf and fzf to fuzzy-search for emoji, and insert the result
function! InsertEmoji(emoji)
    let @a = system('cut -d " " -f 1 | emoji-fzf get', a:emoji)
    normal! "agP

command! -bang Emoj
  \ call fzf#run({
      \ 'source': 'emoji-fzf preview',
      \ 'options': '--preview ''emoji-fzf get --name {1}''',
      \ 'sink': function('InsertEmoji')
      \ })
" Ctrl-e in normal and insert mode will open the emoji picker.
" Unfortunately doesn't bring you back to insert mode 😕
map <C-e> :Emoj<CR>
imap <C-e> <C-o><C-e>

Alternative setup

If you prefer not to use fzf's preview feature and have the emojis appear before their aliases you can use the following alias instead:

alias emoj="emoji-fzf preview --prepend | fzf | awk '{ print \$1 }'"

Custom emoji aliases

emoji-fzf uses a pre-defined set of aliases for every emoji. If you want to define your own, ie add custom aliases for some emojis you can do this via the --custom-aliases flag.

Please note that these aliases will be appended to the list of pre-defined aliases and not replace them.

  1. First you need to create a JSON file with the following structure:
    "👍": [
    "💯": [
  1. Now you can call emoji-fzf like so:
emoji-fzf --custom-aliases /path/to/your-custom-aliases.json preview


This uses a Dockerfile to keep the test build environment relatively clean and locked. The full test infrastructure is:

  • Docker container, based on Ubuntu 20.04
  • tox to run the tests + build checks
  • pre-commit to run isort, black, etc.
  • check-wheel-contents for built wheel sanity

To run the test suite in docker just as CI does:


Building package for publishing

This just uses old timey setuptools:

python sdist bdist_wheel

Use twine to upload to pypi.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

emoji-fzf-0.8.0.tar.gz (54.7 kB view hashes)

Uploaded source

Built Distribution

emoji_fzf-0.8.0-py2.py3-none-any.whl (50.1 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page