Install Z shell (zsh)

Synopsis #

Z shell, normally called zsh, is an interactive shell and scripting language available through OpenBSD packages. This guide installs the package, verifies its registered login-shell path, changes one user’s login shell, and creates a minimal configuration without depending on a third-party configuration framework.

OpenBSD’s base system includes ksh(1) . Installing zsh is optional and does not replace the shell used by system scripts.

Install the Package #

Install zsh with pkg_add(1) :

doas pkg_add zsh

Confirm the installed executable and its entry in shells(5) :

command -v zsh
  # Display the executable selected by the current PATH
grep '^/usr/local/bin/zsh$' /etc/shells
  # Confirm that the package registered zsh as a permitted login shell

The package normally installs the executable as /usr/local/bin/zsh and registers it in /etc/shells. Investigate the package installation if either check fails. Do not add an unverified path to /etc/shells.

Change the Login Shell #

Use chsh(1) as the target user:

chsh -s /usr/local/bin/zsh

The new login shell starts at the next login. Confirm the account database entry with getent(1) :

getent passwd "$USER"

Keep an existing login session open while testing the new shell. A syntax error in a user startup file can then be repaired from the working session.

Create a Minimal Configuration #

When no startup files exist, the first interactive zsh session may offer the zsh-newuser-install configuration helper. It can create a basic ~/.zshrc. A short, hand-written configuration also works:

touch ~/.zshrc
  # Create the file without replacing existing content
chmod 600 ~/.zshrc
  # Restrict the user configuration to its owner

Add settings one at a time and test each change. The following example enables completion and saves a modest command history:

autoload -Uz compinit
compinit

HISTFILE=$HOME/.zsh_history
HISTSIZE=1000
SAVEHIST=1000
setopt append_history

Start a clean interactive shell to test the configuration:

zsh

If startup fails, bypass user startup files with:

zsh -f

Third-party frameworks can execute code during every shell startup and may replace substantial parts of ~/.zshrc. They are outside the base installation procedure and should be reviewed, pinned, and maintained separately if used.

Return to the Base Shell #

To restore OpenBSD’s base Korn shell as the login shell:

chsh -s /bin/ksh

Log out and log in again, then remove the zsh package only after confirming that no account still uses it as a login shell.

Report a bug