I last tested these instructions on macOS Ventura 13.3.1.

Introduction

Antigen and Oh My Zsh are a great combination that allows you to customize Zsh to your liking easily.

In this step-by-step guide, you'll learn how to install both in six easy steps.

What is Antigen, and why do I need it?

Even though Zsh is great, it doesn't offer a plugin management system to easily add, update, and remove third-party plugins.

Antigen is a plugin manager for Zsh. It simplifies managing Zsh plugins by providing a straightforward configuration format that lets users specify the plugins they want to use. In addition, Antigen handles downloading, updating, and loading those plugins, making it convenient to enhance Zsh with additional features and customization options.

Antigen call plugins as bundles, so I'll use both terms interchangeably for this guide.

We'll install Oh My Zsh as an Antigen plugin.

What is Oh My Zsh, and why do I need it?

Now you might be thinking, why do I need Oh My Zsh if I have Antigen? And that's a great question I asked myself.

Antigen makes it very easy to manage dozens of plugins for Zsh, but how do we browse and curate all the plugins out there? That's a gap that Oh My Zsh fills amazingly well.

Oh My Zsh is a very popular framework for managing your Zsh configuration and a hub for more than 300 plugins and 150 syntax highlighting themes that we can easily install. That makes browsing and managing different plugins much easier.

Prerequisite: Git

If you don't have Git installed on your macOS or need clarification, head to my guide on How to install Git with Homebrew on macOS.

Step 1. Install Antigen on macOS

There are two main ways to install Antigen on macOS.

We can install it by using their official installation script by running the following command:

Or we can install it using Homebrew. Since I use Homebrew for other tools, I'll use it because I find it easier to manage everything I can with one package manager.

If you want to install Antigen with Homebrew too but need to install it or need clarification, head to my guide on How to install and use Homebrew on macOS.

It's a good practice to first update Homebrew itself:

To install Antigen with Homebrew, run the following:

You should see a bunch of output and something like the following close to the end:

That means Homebrew installed Antigen successfully! But it still needs to be activated.

Step 2. Using Antigen: the ~/.zshrc file

We use Antigen by setting it up in our ~/.zshrc file.

If you know the ~/.zshrc file and how to use it, you can skip to the next section.

Zsh automatically reads some files at certain moments. The ~/.zshrc file is one of them, and Zsh evaluates it every time it starts. We should use such files to add our custom configurations to Zsh, like what we will do with Antigen.

To check if you have your ~/.zshrc run the following two commands:

And look for that file. You should see it listed after a file named .zsh_sessions.

If you don't have it, create it by running the following command:

You can read more about those files and how to use them in this StackExchange topic.

Step 3. Using Antigen: adding configuration to your ~/.zshrc file

Now open your ~/.zshrc file and add the following to it:

If you are not sure how to open that file, you can use a few options, including opening the built-in TextEditor from the command line by running the following:

For more information about each bundle (plugin) used above, here are their links:

antigen use oh-my-zsh

antigen bundle unixorn/autoupdate-antigen.zshplugin
antigen bundle zsh-users/zsh-autosuggestions
antigen bundle zsh-users/zsh-completions
antigen bundle zsh-users/zsh-syntax-highlighting

antigen bundle command-not-found
antigen bundle git
antigen bundle history-substring-search
antigen bundle magic-enter

antigen theme robbyrussell

Other plugins you might be interested in:

antigen bundle copyfile
antigen bundle nvm
antigen bundle rbenv
antigen bundle rsync
antigen bundle ssh-agent

The above ~/.zshrc file is just an example of how you can have several plugins added to it. I only added general programming stuff that many programmers would like to have and omitted specific plugins like language ones so that the file can work as a nice starting point for your needs.

Feel free to review it and remove any plugins you don't like or won't use. It's a personal matter, and there's virtually a plugin for anything you can think of, which is great because it's up to you to choose what fits your needs. I would first look for plugins on Oh My Zsh's plugins list page.

Step 4. Activating Antigen

Now you need to open a new Terminal window or tab so Zsh can read your ~/.zshrc file and activate Antigen, installing all plugins you listed. Alternatively, you can run the following command to reload your current shell, making it read your ~/.zshrc file:

You must do either step above every time you change your ~/.zshrc file.

You should see a bunch of Installing output lines. That means it is now activated and installed your plugins. Double-check your output to see if you've got any error messages, as some plugins might require additional configuration.

If you added a syntax highlighting theme (included in the config above), it should also be working by now, and you should be able to see some colors! 🌈 Nice, huh?

Step 5. Adding more plugins

To add a plugin from Oh My Zsh, you use their name as follows:

That's because Oh My Zsh is the default repository for Antigen.

To add plugins for any other repository, you usually type their GitHub path, for example:

The line above will add the plugin located at github.com/zsh-users/zsh-syntax-highlighting.

The only rule regarding adding plugins to your ~/.zshrc file is to list them before the antigen apply line.

To learn more about Antigen commands like antigen bundle, antigen theme, and antigen apply, check the official Commands doc page.

Themes work like plugins, i.e., if it's from the Oh My Zsh repo, you type their name after antigen theme. Otherwise, you use the GitHub path.

Step 6. Installing plugins and themes

Whenever we change our ~/.zshrc file, we need to open a new Terminal window or run the following command to make it take effect:

By doing that now, we should see Antigen installing our plugins, so go ahead and take either step.

How to have your plugins, themes, and Antigen itself automatically updated for you

In the example ~/.zshrc file above, we have the following plugin listed:

That plugin will automatically update all your installed plugins and Antigen itself within a predefined number of days (defaults to 7).

To change that interval, you can define two variables on your ~/.zshrc file before the line listing the plugin, like the following:

And replace 30 with the number of days you want.

How to manually update plugins and themes

If you don't want your plugins, themes, and Antigen itself updated automatically, you should manually run the following command:

If you want to update all your plugins at once, run the command without any plugin name:

The updates downloaded are not immediately available. You have to open a new shell to see the changes or run the following command to make it take effect:

Check the antigen update doc for more information.

How to manually update Antigen itself

If you installed Antigen with Homebrew, it's a good practice to first update Homebrew itself:

Then you can update Antigen by running the following command:

If you installed it with their official installation script, you should run the following command to update it:

How to uninstall plugins and themes

To uninstall plugins and themes from your filesystem, run the following command:

You should see an output like the following:

Ensure you manually remove the plugins you're uninstalling from your ~/.zshrc file. Otherwise, Antigen will install them again the next time you open a shell.

After that, you can reload your Zsh instance by running the following:

How to list all installed plugins

To list all installed plugins, run the following command:

Conclusion

And that's it for this guide. I hope you enjoyed it!

Thank you for reading, and let me know if you have any issues or suggestions in the comments below.

Related posts

How to set up your Mac for software development
How to install and use Homebrew on macOS
How to install Git with Homebrew on macOS
How to install and run Node.js with nvm on macOS
How to generate and use SSH keys on macOS
How to sign Git commits with SSH keys on macOS
How to install Command Line Developer Tools on macOS