# desed: a terminal debugger for sed scripts

> desed is a Rust program with a terminal interface that steps through a sed script forwards and backwards, shows you the pattern space before a substitution runs, and lets you set breakpoints and reload the script as you edit it. The author is candid that it works by emulating parts of sed, which means the line it reports is a good guess rather than a certainty.

**SoptikHa2/desed** — Debugger for Sed: demystify and debug your sed scripts, from comfort of your terminal.

- Repository: https://github.com/SoptikHa2/desed
- Website: https://soptik.tech/articles/building-desed-the-sed-debugger.html
- Stars: 1,219 · Forks: 26
- Language: Rust
- License: GPL-3.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/soptikha2-desed

## A debugger for a language that has none

Desed demystifies and debugs sed scripts, from the comfort of your terminal. It is a command line tool with a TUI that gives you a comfortable interface and a practical debugger, used to step through complex sed scripts.

The feature list is short and specific. You can preview variable values, both of them, meaning the pattern space and the hold space. You can see how a substitute command will affect the pattern space before it runs, which is the feature that matters most, because a substitution that behaves differently on the tenth line than on the first is the classic sed bug. You can step through a sed script both forward and backwards, which no other sed tool does. You can place breakpoints and examine program state. And you get hot reload, so you can see what changes as you edit the source.

The last item in the list is that its name is a palindrome, which tells you something about the tone of the project. The FAQ keeps the joke going, noting that in French desed sounds like décéde, which means die or decease, which is a fitting name for a tool you would use in the situation of needing to debug a sed script.

The project is written in Rust, the licence is GPL-3.0-or-later, the author is Petr Šťastný, and the last push was on 2026-05-16, with the repository not archived.

## How it works, and where it can be wrong

The FAQ answers how it works, and the answer is the most useful thing in the repository.

GNU sed actually provides a pretty useful debugging interface, which you can try yourself with the --debug flag. The problem is that the interface is not interactive, and the author wanted something closer to a traditional debugger.

Then comes the honest caveat, under the question of whether it really works. Sed does not tell which line number it is currently executing, so desed has to emulate parts of sed to guess that, which might not be bulletproof. But it certainly worked well enough to debug tetris without issues.

That is the whole risk profile of the tool, stated by its author. The debugging information comes from emulating sed's own behaviour, so any corner of the language that the emulator does not model exactly will show a wrong line or a wrong pattern space.

The fact that the author tested it against a sed implementation of Tetris is worth noting, because that is a real stress test. A sed program that implements a game loop has nested loops, conditionals, branching and a lot of state, and if the emulator can follow that, the common cases are probably right. It is not a proof, and the author does not claim it is.

For a user, the practical implication is that desed is a thinking tool rather than a verification tool. It shows you what the script seems to be doing, which is usually enough to find the bug.

## The controls are Vim's

The controls section is the second half of what makes the tool pleasant, and they are deliberately Vim's.

You scroll through the source code with the mouse and click a line to toggle a breakpoint. The j, k, g and G keys work as in Vim, and prefixing them with numbers works too, so 12j moves twelve lines down. The b key toggles a breakpoint, and prefixing it with a number toggles the breakpoint on a target line, which is the way you set a breakpoint somewhere specific without scrolling there first.

The stepping keys are s to step forward and a to step backwards. The r key runs to the next breakpoint or the end of the script, and R does the same backwards. The l key instantly reloads the code and continues debugging in exactly the same place as before, which is the hot reload feature reduced to a keystroke. And q quits, with a link to the article on how to exit Vim, because the exit ritual is a joke that only lands if you know the original.

The whole design is one decision: a sed debugger for people who already live in Vim, where the muscle memory transfers and nothing new has to be learned to get value from it. That is a narrower audience than a general debugger, and a much larger one than it sounds.

## Installing it, and the sed you need

Desed is packaged for a lot of systems, and the install commands are short.

On DragonFly BSD and FreeBSD it is pkg install desed. On Fedora it is dnf install desed, and on Void Linux it is xbps-install -S desed. On Alpine Linux the package is in the testing repository as aports/testing/desed. On Arch Linux there are two AUR packages, desed-git and desed for the stable version. There are also precompiled binaries on the releases page.

The Cargo route is the shortest:

```bash
cargo install desed
```

And building from source installs the man page as well:

```sh
git clone https://github.com/soptikha2/desed
cd desed
cargo install --path .
cp "desed.1" "$(manpath | cut -d':' -f1)/man1"
```

The last line is a detail worth copying. The repository ships desed.1, a man page, and the source install copies it into your man path, because the tool is meant to be documented like the rest of your Unix toolbox rather than being a command you have to remember the flags of.

The dependencies are listed right after the install methods. For development, rust and cargo at 1.38.0 or later. At runtime, sed, the GNU version, at 4.6 or later, and desed works on BSD if you have installed gsed. That last clause is a hard requirement rather than a preference, since the tool parses and emulates GNU sed behaviour.

## The Rust implementation, and the two file watchers

The Cargo manifest is small, and two of its entries explain how the hot reload works.

The dependencies are clap 4 with the cargo feature for parsing the command line arguments, ratatui 0.29 for the terminal interface, anyhow for flexible error handling, and cfg-if for easier handling of conditional compilation.

Then there are the platform specific ones. On Linux the watcher is inotify 0.11.0, to watch files and auto-reload on changes. On macOS, DragonFly BSD, FreeBSD, NetBSD and OpenBSD it is kqueue 1.0.6, with the same comment about watching files and auto-reloading on changes.

That is the whole hot reload mechanism, and it is a nice piece of engineering discipline. A file watcher is one of those things that is easy on Linux and awkward on the BSDs and macOS, and rather than pulling in a cross-platform abstraction the project uses the native API on each and keeps the rest of the code identical. The cfg-if dependency is there to make the conditional compilation readable.

The manifest also records the project metadata: version 1.2.2, edition 2018, the GPL-3.0-or-later licence, the keywords awk, debugger, debugging and tui, and the category for development tools and debugging.

The repository layout matches. The src/ directory is the tool, the sed/ directory holds the sed emulation and parsing, desed.1 is the man page, aur/ holds the AUR packaging files, publish.sh is the release script, and there is a Cargo.lock, an img/ directory with the demo animation and a .vscode/ directory.

## The contributing note, and why sed

The contributing section is the most unusual README paragraph in this batch, and it is worth reading in full.

The codebase is currently not under active development, with the author saying he will hopefully get to rewriting the parser, and that he wrote this as his first Rust project and it really shows in the code quality. But he is reviewing and accepting pull requests. And then the line that makes the paragraph: this codebase is human-written, and the author does not mind LLM-assisted or LLM-written code, but if you do not write it by hand, please do review it by hand.

That is a more thoughtful position than most projects take, and it is consistent with the state of the project. The parser is the part that needs rewriting, because it is the part that guesses.

The release history shows the gaps. Version 1.2.0 came in October 2020 and added autoreload and BSD support, v1.2.1 in October 2022 fixed BSD file watch support on armv7, and v1.2.2 in October 2024. The last push was on 2026-05-16, so there is still work landing on the branch even though the author describes the project as not under active development.

The why sed questions in the FAQ are the author's own explanation of the choice, and they are half technical and half aesthetic. Sed is the perfect programming language, especially for graph problems, and the argument is that it is plain and simple and does not clutter your screen with useless identifiers like if, for, while or int. Furthermore, since it does not have things like numbers, it is very simple to use. The last of the why answers is the one that decides it: because sed is the standard stream editor for filtering and transforming text, and someone wrote Tetris in it.

The project description says the same thing more bluntly, and answers the question of whether it is a joke by saying the author thought it was, but apparently it is actually useful for some people.

## Conclusion

Adopt desed if you write sed scripts that have grown past what you can hold in your head, and you are willing to treat the reported line as a strong hint rather than a proof. Do not adopt it as a general text processing tool or as a replacement for understanding sed, and do not expect it to work with BSD sed, since it needs GNU sed at 4.6 or later, or gsed on the BSDs. Before you start, check which sed your system has, and if you intend to contribute, read the contributing note, because the author says the codebase is not under active development, accepts pull requests, and asks that any assisted code be reviewed by hand.

## FAQ

### What does desed do?

It is a terminal UI that debugs sed scripts. You can preview variable values, see how a substitute command will affect the pattern space before it runs, step through a script forwards and backwards, place breakpoints and examine program state, and hot reload the script as you edit it.

### How accurate is the line number desed reports?

Sed does not tell which line number it is currently executing, so desed has to emulate parts of sed to guess that, which the author says might not be bulletproof. It worked well enough to debug a Tetris implementation written in sed, but the reported line is a good hint rather than a proof.

### Which sed does desed need?

GNU sed, version 4.6 or later. The runtime dependency is listed as sed with the GNU version at 4.6 or later, and on BSD the tool works if you have installed gsed. Development additionally needs rust and cargo at 1.38.0 or later.

### How do I install desed?

On Debian and Ubuntu derivatives it is apt install desed, on Arch it is available in the AUR as desed-git and desed for the stable version, and on Alpine it is in the testing repository as aports/testing/desed. The Cargo route is cargo install desed, and building from source with cargo install --path . also lets you copy the shipped desed.1 man page into your man path.

### Is desed still being developed?

The contributing note says the codebase is not under active development, that the author wrote it as a first Rust project and it shows in the code quality, and that he is nevertheless reviewing and accepting pull requests. The releases are v1.2.0 from 2020, v1.2.1 from 2022 and v1.2.2 from 2024, and the last push was on 2026-05-16.

## Sources

- [License: GPL-3.0](https://github.com/SoptikHa2/desed/blob/master/LICENSE)
- [Project website](https://soptik.tech/articles/building-desed-the-sed-debugger.html)
- [README](https://github.com/SoptikHa2/desed/blob/master/README.md)
- [Releases](https://github.com/SoptikHa2/desed/releases)
- [SoptikHa2/desed on GitHub](https://github.com/SoptikHa2/desed)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/soptikha2-desed