Patching suckless software (st - simple terminal)


tags: suckless, terminal


st is a simple terminal implementation for X.

As simple as that. suckless managed to program an slick virtual terminal for your X11 display written in C. But this one is different from all other terminals out there. Configuration is hard-coded into the source code, meaning you need to make build and compile everytime you make a change. This is a feature not a bug, it's supposed to be that way. The idea is to depend less on configurations and keep it simple, stupid. A nice little binary installed in your system and less hassle.


While the number of lines of code are very low and that's a good thing, it has its downsides. You'll find that some basic implementations that all terminals use, are missing in st. For example scrollback, cursor blinking, background opacity for composite display. Yes, you can live without all those, that's for sure! But maybe you'll lack productivity, it really depends on you.


I personally love scrollback, it's really -REALLY- useful. Thankfully some nice humans from the UNIX and FOSS community managed to hack some patches to solve specific problems and add cool features.

Some patches I currently use with st 0.8.4 are the following:

  1. alpha - st-alpha-0.8.2.diff

    • Adds transparency when using a compositor such as picom/compton, xcompmgr.
  2. blinking cursor - st-blinking_cursor-20200531-a2a7044.diff

    • Self explanatory. It enables your cursor to blink. Otherwise it's static by default
  3. desktopentry - st-desktopentry-0.8.2.diff

    • Installs a st.desktop file in /usr/share/applications.
  4. scrollback - st-20201205-4ef0cbd.diff

    • Lets you scrollback and forward to read text and other verbose messages a terminal could produce.
  5. scrollback mouse - st-scrollback-mouse-20191024-a2c479c.diff

    • Do the same using a mouse wheel.
  6. scrollback mouse altscreen - st-scrollback-mouse-altscreen-20200416-5703aa0.diff

    • Allows you to scrollback using mouse when not in MODE_ALTSCREEN. Programs such as less work better with this patch.
  7. netwmicon - st-netwmicon-0.8.4.diff

    • Adds a nice window icon for st. It displays in the taskbar in bar programs like tint2.


Don't be scared. Patches are not that difficult to understand. They are only files containing text that will replace other text.

Yes, you'll experience lots of errors and warnings but that's the typical patching experience.

How to patch? Install patch first. The following command will teach you how to add opacity to your st source code you cloned somewhere using git.

$ patch --dry-run -i ~/Downloads/st-alpha-0.8.2.diff -d /path/to/st

See what we did there? --dry-run prints results as if you did really patch, but nothing occur, no file was overwritten. This is an important parameter you can use to test patches.

If you didn't see any critical errors proceed to patch without --dry-run.

-d parameter points to the directory where st is located.

Building and compiling

We just made our first patch, now it's time to recompile the st binary.

First remove config.h.

$ rm config.h

Build and compile using make.

$ make -C /path/to/st

Install st in your system and make it available for all users.

$ sudo make -C /path/to/st clean install


config.def.h is the specific file where you'll store all settings. Colorschemes, keybindings, opacity, font management, window positioning, etc. Don't ever delete this file.

That's pretty much all you need to learn, if you have any questions feel free to contact or join IRC communities for more help.

Happy hacking!