> ## Content Index
> Fetch the complete content index at: https://nomadianation.thesabear.net/llms.txt
> Use this file to discover other available public pages before exploring further.

# How to Build a zsh Setup Without oh-my-zsh
- URL: https://nomadianation.thesabear.net/zsh-without-oh-my-zsh/
- Published: 2026-11-16T20:20:00.000Z
- Updated: 2026-11-20T13:39:29.000Z
- Author: nomadianation
- Tags: tech, tech-linux, #header-full, #start-here

The line that gave it away was the second one in my `.zshrc`. It read `ZSH_THEME="robbyrussell"`, and it had been there for as long as I had used oh-my-zsh. Further down the same file sat a single line of my own that set the prompt by hand, in my own colours. Every time a shell started, oh-my-zsh loaded its theme, and a moment later my line threw it away. The theme had been dead code the whole time, and I had never noticed, because the framework made it easy not to look.

That small discovery sums up why I rewrote it. I wanted a shell that started faster, carried less, and was mine from the first line to the last. What replaced oh-my-zsh is a handful of short files and a plugin loader of about twenty lines. This guide builds the same setup step by step, with the reason behind every part, so you can take what is useful and leave the rest.

## What oh-my-zsh actually does for you

oh-my-zsh is a framework: a large collection of shell code that sits between zsh and your configuration. When a shell starts, it loads its own library files, sets up its plugin and theme system, loads whichever plugins you have listed, applies a theme, and every so often checks whether it should update itself. It ships with hundreds of plugins and well over a hundred themes, and it is genuinely good at giving a newcomer a pleasant shell in five minutes.

The question worth asking is how much of that you use. My list read `plugins=(git zsh-autosuggestions zsh-syntax-highlighting)`. Only the first of those comes from oh-my-zsh itself, and it is mostly a large set of git aliases. The other two, the ones that make zsh feel modern, are independent projects that happen to install into oh-my-zsh's folder. They never needed the framework at all.

Seen that way, the trade looks different. Every new shell paid for the whole framework to load, to deliver two plugins that work perfectly well without it and a theme that my own prompt overrode. Updates arrived on the framework's schedule rather than mine, and the configuration I depended on every day was mostly code I had never read.

None of this makes oh-my-zsh a bad project. It makes it a general-purpose one, built for everyone's needs at once. A framework with hundreds of plugins is not saving you work if the ones you use never needed it. Once that is clear, writing your own configuration stops looking like a hobby project and starts looking like the smaller job.

## Moving zsh config out of your home folder with ZDOTDIR

The first change is where the configuration lives. By default zsh looks for its files directly in your home folder, which is how home folders end up littered with `.zshrc`, `.zsh_history`, `.zcompdump` and friends. zsh offers a cleaner option through a variable called `ZDOTDIR`. As the [zsh manual's section on startup files](https://zsh.sourceforge.io/Doc/Release/Files.html?ref=nomadianation.thesabear.net) explains, zsh reads its personal startup files from `$ZDOTDIR`, and falls back to your home folder when that variable is unset.

There is one catch, and it decides the design. zsh has to find `ZDOTDIR` before it can use it, so the variable has to be set in a file zsh reads from the home folder anyway. That file is `.zshenv`, which zsh reads for every shell it starts, whether that shell is a login shell, an interactive terminal or a script. So `~/.zshenv` stays in the home folder and holds only a few lines:

```zsh
export ZDOTDIR="$HOME/.config/zsh"
export EDITOR="nano"
export VISUAL="nano"

```

Everything else moves to `~/.config/zsh`. History gets the same treatment. It is data rather than configuration, so it goes where data belongs:

```zsh
HISTFILE="$HOME/.local/state/zsh/history"

```

Create that folder before you start a new shell. zsh will happily write to the file, but it will not create the directory for you, and a missing folder means your history quietly goes nowhere.

## Splitting .zshrc into small files

With a home of its own, the configuration can be organised properly. Instead of one long `.zshrc` that grows a little every month, mine is split into seven files, each with one job, and `.zshrc` does nothing but load them in order:

```zsh
source "$ZDOTDIR/env.zsh"
source "$ZDOTDIR/aliases.zsh"
source "$ZDOTDIR/functions.zsh"
source "$ZDOTDIR/plugins.zsh"
source "$ZDOTDIR/bindings.zsh"
source "$ZDOTDIR/fzf.zsh"
source "$ZDOTDIR/prompt.zsh"

```

The split pays off the first time something misbehaves. If a key binding stops working, there is exactly one file to open. If an alias needs changing, it is in `aliases.zsh` and nowhere else. And because each file is short, it is realistic to read the whole configuration from top to bottom, which is the point of owning it.

> A framework with hundreds of plugins is not saving you work if the ones you use never needed it.

The order is not arbitrary. Environment settings come first, because everything after them may rely on the `PATH` and history settings they define. Plugins load before key bindings, because some bindings refer to widgets the plugins create. The prompt comes last.

That last file is the smallest and the most personal. It holds the prompt itself, written by hand in zsh's own prompt syntax: the user name, the machine name and the current folder, each in its own colour from the 256-colour palette. It is one line, and it replaces the entire theme system. The same file also runs fastfetch, which prints a short summary of the machine every time a terminal opens: the operating system, kernel, uptime, memory and disks. It is the one deliberate cost at start-up in the whole configuration. On a desktop it is decoration, but on a server it answers the first question you usually have after logging in, which is what state the machine is in.

## A plugin loader in twenty lines

Plugin managers exist for zsh just as frameworks do, but two plugins do not need a manager. They need a function that downloads a plugin the first time and loads it every time after that. This is the whole of `plugins.zsh`, minus its comments:

```zsh
ZSH_PLUGIN_DIR="$ZDOTDIR/plugins"
mkdir -p "$ZSH_PLUGIN_DIR"

zsh_load_plugin() {
    local name="$1" repo="$2" entry="$3"
    local dir="$ZSH_PLUGIN_DIR/$name"
    if [ ! -d "$dir" ]; then
        git clone --depth=1 "$repo" "$dir"
    fi
    [ -f "$dir/$entry" ] && source "$dir/$entry"
}

zsh_load_plugin "zsh-autosuggestions" \
    "https://github.com/zsh-users/zsh-autosuggestions" \
    "zsh-autosuggestions.zsh"

zsh_load_plugin "fast-syntax-highlighting" \
    "https://github.com/zdharma-continuum/fast-syntax-highlighting" \
    "fast-syntax-highlighting.plugin.zsh"

unset -f zsh_load_plugin

```

![A laptop showing colourful code in a dark room](https://nomadianation.thesabear.net/content/images/2026/11/zsh-without-oh-my-zsh-2.jpg)

The first plugin, [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions?ref=nomadianation.thesabear.net), shows a faint suggestion as you type, drawn from your history, which you accept with the right arrow key. The second colours the command line as you type, so a mistyped command shows up in red before you press Enter. I use fast-syntax-highlighting, a separate project from the zsh-syntax-highlighting plugin I ran under oh-my-zsh, doing the same job.

The order matters. Syntax highlighting loads last, after autosuggestions. Highlighting plugins work by wrapping the line editor's widgets, so anything that adds widgets of its own should be loaded before them. The final line removes the loader function once it has done its work, so it does not linger in every shell.

The loader has one weakness worth understanding before you copy it. It clones whatever version of each plugin is newest on the day you first open a shell, and every shell after that runs that code. Nothing updates on its own, which sounds safe, but it means the version you get depends on the date you set the machine up, and you are trusting that the project was in a good state that day. If either project were ever compromised, a fresh machine would download and run the result. The fix is to pin each plugin to a release you have chosen:

```zsh
git clone --depth=1 --branch v0.7.1 "$repo" "$dir"

```

Give the loader a fourth argument for the version and pass it to `--branch`, and each plugin gets its own tag. Updating becomes a decision you make on purpose: read the changelog, change the tag, delete the plugin folder and open a new shell.

## History settings that make zsh remember properly

A shell's history is only useful if it records the right things and finds them quickly. These are the settings in `env.zsh`, with what each one does:

```zsh
HISTSIZE=10000
SAVEHIST=10000
setopt APPEND_HISTORY
setopt SHARE_HISTORY
setopt HIST_IGNORE_DUPS
setopt HIST_IGNORE_SPACE
setopt HIST_VERIFY
setopt INC_APPEND_HISTORY

```

![Close-up of a black mechanical keyboard with exposed switches](https://nomadianation.thesabear.net/content/images/2026/11/zsh-without-oh-my-zsh-3.jpg)

The two numbers set how many commands are kept in memory and on disk. `APPEND_HISTORY` adds to the history file instead of overwriting it when a shell exits, and `INC_APPEND_HISTORY` writes each command as soon as it runs rather than waiting for the shell to close. `SHARE_HISTORY` lets open terminals see each other's commands, so something you ran in one window can be recalled in another. `HIST_IGNORE_DUPS` stops a command from being recorded twice in a row.

Two settings deserve more attention. `HIST_IGNORE_SPACE` keeps any command that starts with a space out of the history file. It is the simplest protection there is for the occasional command that carries something sensitive: type a space first, and it is never written down. It stays recallable only until you run the next command. `HIST_VERIFY` changes what happens with history shortcuts such as `!!`. Instead of running the expanded command immediately, zsh puts it on the command line for you to check first, so a shortcut that expands to something unexpected never runs unseen.

The last piece is searching. In `bindings.zsh`, the Up and Down arrows are bound to search by prefix: type `docker` and press Up, and zsh steps back only through commands that begin with `docker`. The binding uses `history-search-end`, a small function that ships with zsh, so that the cursor lands at the end of the recalled line rather than in the middle of it:

```zsh
autoload -Uz history-search-end
zle -N history-beginning-search-backward-end history-search-end
zle -N history-beginning-search-forward-end history-search-end
bindkey '^[[A' history-beginning-search-backward-end
bindkey '^[[B' history-beginning-search-forward-end

```

The same file binds Ctrl with the left and right arrows to move a word at a time, and Ctrl+\\ to turn suggestions on and off, using a widget the autosuggestions plugin already provides:

```zsh
bindkey '^\' autosuggest-toggle

```

## Fuzzy search with fzf: Ctrl+R, Ctrl+T and Ctrl+F

![A desk with illuminated keyboards and screens showing code](https://nomadianation.thesabear.net/content/images/2026/11/zsh-without-oh-my-zsh-4.jpg)

The biggest single improvement to daily use is not a zsh plugin at all. [fzf](https://github.com/junegunn/fzf?ref=nomadianation.thesabear.net) is a general-purpose fuzzy finder: give it a list, type a few letters from anywhere in the item you want, and it narrows the list as you type. It ships with zsh key bindings of its own, the most useful being Ctrl+R to search history and Ctrl+T to find a file and paste its path onto the command line.

Loading those bindings is where distributions disagree. On Fedora and the Red Hat family, fzf's shell scripts live in `/usr/share/fzf/shell`. On Debian and Ubuntu they are in `/usr/share/doc/fzf/examples`. Rather than maintain two configurations, `fzf.zsh` checks both places and loads whichever exists. Recent versions of fzf make this simpler with a single line, `source <(fzf --zsh)`, but older packages in stable distributions do not support it, and checking the paths works everywhere.

fzf finds files by walking the folder tree itself, but it can use any command that prints a list of files. Pointing Ctrl+T at fd, a fast and simpler alternative to `find`, suits large folders well, and fd skips hidden files by default:

```zsh
export FZF_CTRL_T_COMMAND="fd --type f --strip-cwd-prefix"

```

Sometimes the file you want is hidden, such as a configuration file, so a third binding fills the gap. Ctrl+F runs the same search with hidden files included, leaves out the `.git` folder, and pastes the result where the cursor is. It is a few lines of shell, registered with `zle -N` as a widget and bound to a key. The same pattern covers the configuration's own Ctrl+R, which lists the history with zsh's `fc` command and passes it through fzf. Once you have written one widget like this, you can write a fuzzy picker for almost anything.

## Aliases and functions worth keeping

Aliases are where personal configurations usually sprawl, so mine follow one rule: an alias must either save real typing or make a command safer to read. The docker compose shortcuts, `dcu`, `dcd`, `dcr` and `dcp` for up, down, restart and pull, earn their place many times a day.

The more interesting aliases are conditional. eza is a modern replacement for `ls` that adds a git status column and a tree view, and bat is a replacement for `cat` with syntax highlighting. Neither is in every distribution's repositories, so the aliases only switch over when the tool is actually installed:

```zsh
if command -v bat >/dev/null 2>&1; then
    alias cat='bat'
fi

```

bat is also well behaved in pipelines: when its output goes to another command rather than to the screen, it prints plain text like `cat` would, so the alias does not break scripts that read its output. There is one more distribution difference to absorb here. Debian and Ubuntu install fd and bat under the names `fdfind` and `batcat`, because the shorter names were already taken by other packages. Two symbolic links in `~/.local/bin`, which `env.zsh` puts on the `PATH`, give them their usual names, and the rest of the configuration never has to know.

Functions handle what aliases cannot. `cd` is wrapped so that changing folder also lists it, which folds one of the most common pairs of commands into one. `mkcd` makes a folder and moves into it. `extract` unpacks the common archive formats without anyone having to remember which letters `tar` wants for which compression. `ports` lists every listening port with the process behind it, and `reload` re-reads the configuration after an edit.

One function deserves a warning. `killport` stops whatever is listening on a given port, using `kill -9`. That signal cannot be caught, so the process gets no chance to finish writing files or close connections cleanly. It is the right tool for something truly stuck and the wrong first choice for anything else. If you copy it, consider trying a plain `kill` first.

![A mechanical keyboard with an orange accent key on a wooden table](https://nomadianation.thesabear.net/content/images/2026/11/zsh-without-oh-my-zsh-5.jpg)

Every key earns its place

## What you give up, and why it is worth it

Leaving a framework has real costs, and it is worth being clear about them. The themes are gone, though a hand-written prompt is one line and says exactly what you want it to. Automatic updates are gone, and with pinned plugins that becomes a feature rather than a loss. The large set of git aliases is gone, and the handful you actually type are easy to write yourself.

What you gain is harder to list but easy to feel. The shell starts faster, because it loads only what you asked for. The whole configuration is short enough to read in one sitting, and when something behaves strangely, the answer is in a file you wrote. Because the differences between distributions are handled inside the configuration, the same files work on Fedora, Debian and everything between, and a new machine feels like home within a minute of the first login.

The deeper change is in how you relate to your tools. A framework is something you rent: it works until it does not, and when it does not, you are reading someone else's code under pressure. A configuration you built is something you own. Every line has a reason you can explain, and that makes the next improvement a small, confident edit rather than a search through a plugin directory.