How to Set Up ZSH on macOS: Complete Guide with Oh My Zsh

Introduction

ZSH (Z shell) is a modern and extensible command-line shell that became the default on macOS Catalina (version 10.15) instead of Bash. It offers many improvements: intelligent autocompletion, support for color themes, plugins, and convenient features like command history with search. Configuring ZSH can significantly boost your terminal productivity, making it not only functional but also visually appealing.

In this guide, you will learn how to set up ZSH on macOS using the Oh My Zsh framework, which simplifies configuration, theme, and plugin management. After completing it, you will have a personalized terminal tailored to your tasks.

Requirements

Before you begin, ensure you have:

• macOS 10.15 (Catalina) or newer (ZSH is pre-installed). For older macOS versions, you may need to install ZSH manually.
• Access to Terminal or a third-party emulator like iTerm2.
• Internet connection to download Oh My Zsh and plugins.
• Homebrew is recommended for easy package management, but not strictly necessary.

If you're unsure whether ZSH is installed, run in your terminal:

zsh --version

If the command returns a version (e.g., zsh 5.8), ZSH is installed. If not, proceed to the installation step in the instructions below.

Step 1: Install ZSH (If Necessary)

On modern macOS versions (Catalina and above), ZSH is already pre-installed. However, on older systems (like Mojave or Sierra), it might be missing. In that case, install ZSH using Homebrew:

brew install zsh

After installation, set ZSH as your default shell:

chsh -s /bin/zsh

Enter your administrator password when prompted. Then restart your terminal for the changes to take effect.

💡 Tip: If Homebrew is not installed, you can install ZSH by downloading the source code from the official website or using your system's package manager. However, Homebrew greatly simplifies the process.

Step 2: Install Oh My Zsh

Oh My Zsh is a framework for managing ZSH configuration, which comes with numerous themes and plugins. Installation is done via a single script.

Run in your terminal:

sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Or, if you have wget installed:

sh -c "$(wget -O- https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

The script will automatically:

• Clone the Oh My Zsh repository into ~/.oh-my-zsh.
• Back up your existing ~/.zshrc file (if it exists) and replace it with a template.
• Set ZSH as the default shell if it hasn't been done already.

After installation, the terminal will restart automatically, and you'll see a new command prompt with the default theme (usually robbyrussell).

⚠️ Important: Ensure you have write permissions in your home directory. If the installation fails, check your internet connection and try again.

Step 3: Choose and Configure a Theme

Oh My Zsh comes with over 100 ready-to-use themes that change the appearance of your command prompt, including colors, current directory display, Git status, and other information.

To change the theme:

1. Open the configuration file ~/.zshrc in a text editor. For example, using nano:

   nano ~/.zshrc
   

2. Find the line with the ZSH_THEME variable. By default, it looks like:

   ZSH_THEME="robbyrussell"
   

3. Replace the value with the name of your desired theme. For example, for the popular agnoster theme:

   ZSH_THEME="agnoster"
   

   
   A list of available themes is located in the ~/.oh-my-zsh/themes/ directory. You can view them by running:

   ls ~/.oh-my-zsh/themes/
   

4. Save the file (in nano, press Ctrl+X, then Y and Enter) and close the editor.
5. Apply the changes by running:

   source ~/.zshrc
   

Your command prompt should now update. Some themes (like agnoster) require special fonts, such as Powerline, to display symbols correctly. If symbols appear incorrectly, install the Powerline font:

brew tap homebrew/cask-fonts
brew install --cask font-hack-nerd-font

Then configure your terminal to use this font in the profile settings.

Step 4: Add Plugins

Plugins extend ZSH's functionality by adding features like syntax highlighting, command suggestions based on history, Git integration, and more.

Oh My Zsh includes several built-in plugins. To activate them:

1. Open the ~/.zshrc file.
2. Find the plugins variable. By default, it may be empty or contain git:

   plugins=(git)
   

3. Add the desired plugins inside the parentheses, separated by spaces. For example, to enable popular plugins:

   plugins=(git zsh-syntax-highlighting zsh-autosuggestions)
   

4. Save the file and run source ~/.zshrc.

Note: The zsh-syntax-highlighting and zsh-autosuggestions plugins are not included in the base Oh My Zsh installation but can be easily added. If you just installed Oh My Zsh, these plugins may already be available in the ~/.oh-my-zsh/custom/plugins/ directory. If not, install them manually:

git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
git clone https://github.com/zsh-users/zsh-autosuggestions.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

Then add them to the plugins list in ~/.zshrc as shown above.

Quick Overview of Popular Plugins:

• git: adds aliases for Git commands (e.g., gco for git checkout) and shows the branch status in the prompt.
• zsh-syntax-highlighting: highlights commands in real-time, indicating syntax errors (red) or correctness (green).
• zsh-autosuggestions: suggests command completions based on your history as you type (gray text, accept with →).
• history-substring-search: allows searching command history by typed characters (use ↑/↓ after typing part of a command).
• web-search: adds aliases for searching Google, GitHub, and other services directly from the terminal.

Experiment with different plugins to find the optimal set for your tasks.

Step 5: Configure Aliases and Environment Variables

You can add your own aliases (command shortcuts) and environment variables to the ~/.zshrc file for automatic loading when ZSH starts.

Adding Aliases

At the end of the ~/.zshrc file, add an aliases block. For example:

# Useful aliases
alias ll='ls -la'
alias la='ls -A'
alias l='ls -CF'
alias gs='git status'
alias ga='git add'
alias gc='git commit'
alias gp='git push'

These aliases simplify frequent commands. Save the file and run source ~/.zshrc.

Exporting Environment Variables

To add environment variables like EDITOR or PATH, use the export command. For example:

export EDITOR="nano"
export PATH="$HOME/bin:$PATH"

This sets nano as the default editor and adds the ~/bin directory to the beginning of PATH.

Step 6: Apply and Verify Changes

After making all changes to ~/.zshrc, you need to reload the ZSH configuration. You can do this in one of the following ways:

• Run in the terminal:

  source ~/.zshrc
  

• Or simply close and reopen the terminal (or tab).

Now all settings should be active.

Verify the Result

Ensure ZSH is working correctly:

1. Check the shell: run echo $SHELL. It should return /bin/zsh or the path to ZSH.
2. Check the theme: if you changed the theme, verify that the command prompt displays with the new style.
3. Check plugins: for example, if the git plugin is enabled, navigate to a Git repository directory and verify that the branch is shown in the prompt.
4. Check aliases: type ll and verify it executes ls -la.
5. Test plugins in action: for zsh-syntax-highlighting, type an incorrect command (e.g., ls --wrong)—it should highlight in red. For zsh-autosuggestions, start typing a command from your history—a suggestion should appear in gray.

If something isn't working, refer to the "Possible Issues" section.

Possible Issues

Common problems that may arise when setting up ZSH:

Oh My Zsh Installation Error

Symptom: The installation script fails with an error like "permission denied" or "curl not found".

Solution:

• Ensure you have write permissions in your home directory. Use sudo only if necessary, but it's usually not required.
• If curl is not installed, install it via Homebrew: brew install curl.
• Check your internet connection and retry the installation.

Theme Not Applying

Symptom: The command prompt doesn't change after editing ~/.zshrc.

Solution:

• Check the ~/.zshrc file for syntax errors. Run zsh -n ~/.zshrc—if the output is empty, there are no errors.
• Ensure the theme name is spelled correctly and the theme exists in ~/.oh-my-zsh/themes/.
• If the theme requires special fonts (e.g., Powerline), install them and configure your terminal.
• After changes, don't forget to run source ~/.zshrc.

Plugins Not Working

Symptom: Plugin functions like syntax highlighting or suggestions are missing.

Solution:

• Ensure plugins are listed in the plugins variable in ~/.zshrc and separated by spaces.
• For plugins not included by default in Oh My Zsh (e.g., zsh-syntax-highlighting), verify they are installed in the ~/.oh-my-zsh/custom/plugins/ directory. If not, clone the repositories as described in Step 4.
• Reload ZSH with source ~/.zshrc or restart the terminal.
• Check for conflicts between plugins. Try temporarily removing some from the list.

ZSH Not Updating After Changes

Symptom: You made changes to ~/.zshrc, but they don't take effect.

Solution:

• Verify you are editing the correct file. For a user, it's located at ~/.zshrc. If you're using system ZSH, the config might be in /etc/zshrc, but this is not recommended.
• Check that you saved the file after editing.
• Run source ~/.zshrc in the same terminal session where you edited the file.
• If the problem persists, restart the terminal completely.

"Command not found" Error for Oh My Zsh Commands

Symptom: Commands like omz are not recognized.

Solution:

• Oh My Zsh adds its functions automatically on startup. Ensure Oh My Zsh is installed correctly (the ~/.oh-my-zsh directory exists).
• If you manually moved or deleted the directory, reinstall Oh My Zsh.

For additional help, consult the official Oh My Zsh documentation or the community.

This concludes the ZSH setup on macOS. You should now have a powerful and customized shell that will speed up your terminal work. Experiment with themes and plugins to find your perfect setup!