Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



What is it?

smenu is a selection filter just like sed is an editing filter.

This tool takes words from standard input or from a file and presents them on the screen in different layouts in a scrolling window. A cursor that you can easily move with the keyboard and/or the mouse lets you select one or more of them.

Note that the screen is not cleared at the beginning and end of the smenu execution. The selection window is displayed at the cursor position and the previous contents of the terminal are not changed or lost.

I tried to make its use as simple as possible. It supports the UTF-8 encoding and should work on all terminals managed by the terminfo database.

Please refer to the included man page to learn more about this little program.

The wiki contains screenshots and animations that detail some concepts and features of smenu.

How to build it?

Some Linux distributions already provide smenu as a package, if not, smenu can be built on any system on which a functional terminfo development platform is available. This includes all Unix and Unix-like systems that I know of.

Please use the provided script to build the executable. This script uses and accepts the same arguments as the GNU configure script, type --help to see them.

How to install it?

Once the build process is complete, a simple make install with the appropriate privileges will do it.

Issue vs Discussion.

I have enabled discussions on this repository.

I am aware there may be some confusion when deciding where you should communicate when reporting issues, asking questions or raising feature requests so this section aims to help us align on that.

Please raise an issue if:

  • You have found a bug.
  • You have a feature request and can clearly describe your request.

Please open a discussion if:

  • You have a question.
  • You're not sure how to achieve something with smenu.
  • You have an idea but don't quite know how you would like it to work.
  • You have achieved something cool with smenu and want to show it off.
  • Anything else!

Some examples.

Linux example.

This program should work on most Unix but if you are using Linux, try to type the following line at a shell prompt (here: "$ " ):

$ R=$(grep Vm /proc/$$/status \
      | smenu -n20 -W $':\t\n' -q -c -b -g -s /VmH)
$ echo $R

Something like this should now be displayed with the program waiting for commands: (numbers are mine, yours will be different)

VmPeak¦    23840 kB
VmSize¦    23836 kB
VmLck ¦        0 kB
VmHWM ¦     2936 kB
VmRSS ¦     2936 kB
VmData¦     1316 kB
VmStk ¦      136 kB
VmExe ¦       28 kB
VmLib ¦     3956 kB
VmPTE ¦       64 kB
VmSwap¦        0 kB

A cursor should be under "VmHWM ".

After having moved the cursor to " 136 kB" and ended the program with <Enter>, the shell variable R should contain: " 136 kB".

Unix example.

The following command, which is Unix brand agnostic, should give you a scrolling window if you have more than 10 accounts on your Unix with a UID lower than 100:

$ R=$(awk -F: '$3 < 100 {print $1,$3,$4,$NF}' /etc/passwd \
      | smenu -n10 -c)
$ echo $R

On mine (LANG and LC_ALL set to POSIX) it displays:

at      25 25  /bin/bash      \
sys     0  3   /usr/bin/ksh   +
bin     1  1   /bin/bash      |
daemon  2  2   /bin/bash      |
ftp     40 49  /bin/bash      |
games   12 100 /bin/bash      |
lp      4  7   /bin/bash      |
mail    8  12  /bin/false     |
named   44 44  /bin/false     |
ntp     74 108 /bin/false     v

Note the presence of a scroll bar.

Bash example (CRTL-R replacement)

Just add the following in your .bashrc

bind -x '"\C-r": READLINE_LINE=$(fc -lr 1                         \
                                 | sed "s/[1-9][0-9]*..//"        \
                                 | smenu -Q -l -a c:7/4,b -W"$EOL")

Launch or relaunch bash and hit CTRL-R (CTRL-C or q to exit), enjoy!

You can also add the parameter -d to instruct smenu to clean the selection window after selecting an entry.

Warning for post v0.9.15 versions.

These versions use a new options system called ctxopt which may contain bugs. Please report them so they can be fixed in the next release of smenu or ctxopt (

Command line arguments may also need to be rearranged in some cases because of this new option management system. Sorry for the extra work this might entail.

Testing and reporting.

The included testing system is relatively young, please be indulgent.

IMPORTANT the testing system has some dependencies, please read the test/README.rst before going further.

NOTE running all the tests by running ./ in the tests directory will take some time (around 21 min for now).

NOTE on some systems like *BSD some tests may fail. This can be explained by differences in posix/libc/... implementations. This can notably occur when some specific regular expressions or uncommon UTF-8 byte sequences are used.

If a test fails for an unknown reason, please send me the name of its directory and the corresponding .bad file.

If you are hit by a bug that no test covers, then you can create a new test in the tests directory in an existing or new directory: read the tests/README.rst file, use an existing test as model, create an .in file and a .tst file and send them to me as well as the produced files.


Contributions are welcome but discuss your proposal in an issue first, or with the maintainer.

Special thanks.

I want to thank those who took the time to package smenu for their preferred operating system or distribution. You will find their names here:


smenu started as a lightweight and flexible terminal menu generator, but quickly evolved into a powerful and versatile CLI selection tool for interactive or scripting use.








No packages published

Contributors 4