peco

Fuzzy Finders•

•Go

Interactive filtering tool for UNIX pipes.

Official Website

Features

Interactive FilteringCustom ActionsMultiple Selection

Installation

Homebrew

brew install peco

APT (Debian/Ubuntu)

apt install peco

Pacman (Arch)

pacman -S peco

Why Use peco?

peco is a simple and easy-to-use fuzzy finder developed in Japan. It works immediately with no configuration needed, embodying the Unix pipeline philosophy.

Simple Design

No complex configuration needed. Works immediately after installation with intuitive operation. Low learning curve.

Unix Pipeline

Accepts from standard input and outputs to standard output. Excellent compatibility with Unix toolchains.

Fast Performance

Implemented in Go, lightweight and fast. Handles large amounts of data without stress.

Japanese-Friendly

A tool developed in Japan with comprehensive Japanese documentation. Large user base in the Japanese community.

Installation

# macOS (Homebrew)
brew install peco

# Ubuntu/Debian (Download from GitHub Releases)
# Download the latest version from https://github.com/peco/peco/releases
wget https://github.com/peco/peco/releases/download/v0.5.11/peco_linux_amd64.tar.gz
tar xzf peco_linux_amd64.tar.gz
sudo mv peco_linux_amd64/peco /usr/local/bin/

# Arch Linux
sudo pacman -S peco

# Install with Go
go install github.com/peco/peco/cmd/peco@latest

Basic Usage

Pipeline Basics

Basic Commands

# Select from file list
ls | peco

# Combine with find command
find . -type f | peco

# Open selected file with vim
vim $(ls | peco)

# Multiple selection (-m option)
ls | peco -m

Practical Usage Examples

Examples

# Select and execute from command history
$(history | peco | awk '{$1=""; print substr($0,2)}')

# Kill a process
ps aux | peco | awk '{print $2}' | xargs kill

# Switch git branch
git branch | peco | xargs git checkout

# Select commit from git log
git log --oneline | peco | awk '{print $1}'

# Select SSH host and connect
grep "^Host " ~/.ssh/config | awk '{print $2}' | peco | xargs -I{} ssh {}

# Select docker container
docker ps | peco | awk '{print $1}'

peco Output Example

QUERY> config_

> .zshrc

.gitconfig

.config/nvim/init.lua

.config/starship.toml

package.json

[5/128]

Real-time filtering based on query input. Simple and clean interface.

Shell Integration

Unlike fzf, peco doesn't have built-in shell integration, but you can configure similar functionality yourself.

Ctrl+R History Search (Zsh)

Zsh History Search

# Add to ~/.zshrc

# Search command history with peco
function peco-history-selection() {
    BUFFER=$(history -n -r 1 | peco --query "$LBUFFER")
    CURSOR=$#BUFFER
    zle reset-prompt
}
zle -N peco-history-selection
bindkey '^R' peco-history-selection

Ctrl+R History Search (Bash)

Bash History Search

# Add to ~/.bashrc

# Search command history with peco
function peco-history() {
    local selected=$(history | tac | sed 's/^[ ]*[0-9]*[ ]*//' | peco --query "$READLINE_LINE")
    READLINE_LINE="$selected"
    READLINE_POINT=${#READLINE_LINE}
}
bind -x '"\C-r": peco-history'

Directory Navigation

# Add to ~/.zshrc

# Select and change directory with peco
function peco-cd() {
    local dir=$(find . -maxdepth 5 -type d | peco)
    if [ -n "$dir" ]; then
        cd "$dir"
    fi
}
alias pcd='peco-cd'

# Integration with ghq (Repository management)
function peco-ghq() {
    local repo=$(ghq list | peco)
    if [ -n "$repo" ]; then
        cd "$(ghq root)/$repo"
    fi
}
alias pg='peco-ghq'

Useful Aliases

# Add to ~/.bashrc or ~/.zshrc

# Select and edit file
alias pe='vim $(find . -type f | peco)'

# Switch git branch
alias pgb='git branch | peco | xargs git checkout'

# Interactive git add
alias pga='git status -s | peco | awk "{print \$2}" | xargs git add'

# Kill process
alias pkill='ps aux | peco | awk "{print \$2}" | xargs kill -9'

# Change directory
alias pcd='cd $(find . -type d | peco)'

# Enter docker container via exec
alias pdexec='docker exec -it $(docker ps | peco | awk "{print \$1}") /bin/bash'

# Select SSH host
alias pssh='ssh $(grep "^Host " ~/.ssh/config | awk "{print \$2}" | peco)'

# Select and run npm scripts
alias pnpm='npm run $(cat package.json | jq -r ".scripts | keys[]" | peco)'

peco Key Bindings

Key	Action
`Ctrl+N / Down Arrow`	Move to next item
`Ctrl+P / Up Arrow`	Move to previous item
`Enter`	Confirm selection
`Ctrl+Space`	Multiple selection (with -m option)
`Ctrl+A`	Move cursor to line start
`Ctrl+E`	Move cursor to line end
`Ctrl+C / Esc`	Cancel
`Ctrl+U`	Clear input
`Ctrl+R`	Toggle search matcher

Configuration File

Detailed configuration is possible via ~/.config/peco/config.json.

~/.config/peco/config.json

{
  "Prompt": "QUERY> ",
  "InitialMatcher": "Fuzzy",
  "Style": {
    "Basic": ["on_default", "default"],
    "SavedSelection": ["bold", "on_yellow", "white"],
    "Selected": ["underline", "on_cyan", "black"],
    "Query": ["yellow", "bold"],
    "Matched": ["red", "on_default"]
  },
  "Keymap": {
    "C-p": "peco.SelectPrevious",
    "C-n": "peco.SelectNext",
    "C-d": "peco.ScrollPageDown",
    "C-u": "peco.ScrollPageUp",
    "C-a": "peco.BeginningOfLine",
    "C-e": "peco.EndOfLine",
    "C-w": "peco.DeleteBackwardWord",
    "C-space": "peco.ToggleSelection"
  },
  "CustomMatcher": {
    "Migemo": ["/usr/local/bin/cmigemo", "-q", "-d", "/usr/local/share/migemo/utf-8/migemo-dict"]
  }
}

Search Matchers

peco supports multiple search algorithms that can be switched with Ctrl+R.

Matcher	Description	Option
Fuzzy	Fuzzy search (default)	`--initial-matcher Fuzzy`
IgnoreCase	Case-insensitive partial match	`--initial-matcher IgnoreCase`
CaseSensitive	Case-sensitive partial match	`--initial-matcher CaseSensitive`
Regexp	Regular expression match	`--initial-matcher Regexp`

Matcher Specification

# Launch in regex mode
ls | peco --initial-matcher Regexp

# Launch in case-insensitive mode
ls | peco --initial-matcher IgnoreCase

Common Options

Option	Description	Example
`--query`	Specify initial query	`peco --query "test"`
`--prompt`	Specify prompt string	`peco --prompt "SELECT> "`
`--layout`	Layout (top-down/bottom-up)	`peco --layout bottom-up`
`--selection-prefix`	Prefix for selected line	`peco --selection-prefix ">> "`
`--rcfile`	Specify config file	`peco --rcfile ~/.peco.json`
`--select-1`	Auto-select if only one candidate	`peco --select-1`
`--on-cancel`	Action on cancel	`peco --on-cancel error`

Comparison with fzf

Feature	peco	fzf
Language	Go	Go
Shell Integration	Manual setup required	Built-in support
Preview Feature	Not available	Available
Configuration Ease	Intuitive JSON format	Environment variables/options
Japanese Documentation	Comprehensive	Limited
Vim Integration	Limited	Extensive with fzf.vim
Feature Richness	Simple	Feature-rich

Choose peco for simplicity, fzf for more features.

Tips

•Combined with ghq, Git repository management becomes significantly more convenient
•For Japanese search, migemo integration is recommended (enables Japanese search using Romaji)
•Using the --select-1 option automatically selects when there's only one candidate
•If you need preview functionality, consider using peco with fzf
•Ctrl+R switches matchers (Fuzzy → IgnoreCase → CaseSensitive → Regexp)
•You can define custom matchers in the config file (such as migemo)

fzf - Command-line Fuzzy Finder

General-purpose command-line fuzzy finder

tools10 min read

skim - Rust fzf Alternative

Fuzzy finder in Rust with fzf-compatible interface

tools6 min read

Explore More

Browse Fuzzy Finders

See all tools in this category

All CLI Tools

Explore all tool categories

Features

Installation

Why Use peco?

Simple Design

Unix Pipeline

Fast Performance

Japanese-Friendly

Installation

Basic Usage

Pipeline Basics

Practical Usage Examples

peco Output Example

Shell Integration

Ctrl+R History Search (Zsh)

Ctrl+R History Search (Bash)

Directory Navigation

Useful Aliases

peco Key Bindings

Configuration File

Search Matchers

Common Options

Comparison with fzf

Tips

Related Articles

fzf - Command-line Fuzzy Finder

skim - Rust fzf Alternative

Explore More