This quickstart includes the powerlevel10k ZSH theme, which requires a Powerline-compatible font in your terminal to display certain status glyphs. Fonts that are Powerline-compatible include many useful glyphs, including the nice branch icon that the theme in this
Here are a few good Powerline-compatible fonts:
brew install stow
zshthan the one Apple ships with the OS, so
brew install zshto install it.
/usr/local/bin/zshif you decided to use the newer version packaged by
chsh -s /bin/zsh
yum install -y stowon Red Hat / CentOS systems,
apt-get -y install stowon Debian / Ubuntu.
mv YourChosenPowerlineFont.otf ~/.fonts
fc-cache -vf ~/.fonts/
After installing a Nerdfont or Powerline-compatible font, you will also need to configure your terminal emulator to use your selected Powerline-compatible font. The name of the correct font usually ends with for Powerline.
If the Powerline symbols cannot be seen, try closing all instances of the terminal emulator. The X Server may also need to be restarted for the new font to correctly load.
If you still can’t see the new fonts then double-check that the font has been installed to a valid X font path.
If you get garbled branch glyphs, make sure there isn't a separate font setting for non-ASCII characters in your terminal application that you also need to set to use a Powerline-compatible font. Konsole needs to be set to use UTF-8 encoding, for example.
Now that your fonts and default shell have been set up, install zgen and the dotfiles from this starter kit repository.
git clone [email protected]:tarjoilija/zgen.git
git clone [email protected]:unixorn/zsh-quickstart-kit.git
.zsh-completionsfrom this repo into your
stow --target=/Users/YourUsername zsh. Replace
/home/YourUsernameif you're on Linux. If you still have errors, symlink the files in zsh into your home directory.
.zsh_functions files included in this kit enable the plugins listed below.
The zsh-quickstart-kit configures your ZSH environment so that it includes:
zshsessions on the same machine.
--helpoutput. Note that this doesn't happen dynamically, you'll have to explicitly run it to create a completion for each command missing one.
kis a directory lister that also shows git status on files & directories.
zgenitself, and your plugins) to
githelper scripts for bitbucket.
fzf-powered history search.
$PATHif you're running macOS to allow you to use the same plugin list on macOS and other systems.
The quickstart kit also uses
zgen to load oh-my-zsh and these plugins:
Running the following commands will toggle behavior the next time you start a shell session:
zsh-quickstart-disable-omz-plugins - Makes the stock quickstart not load any of the oh-my-zsh plugins it would normally use. You can re-enable them for new shell sessions with
Prompt selectors - We now use the powerlevel10k prompt. I won't change the prompt out from under people without a way for them to get the old behavior, so there are commands to switch back and forth.
You can disable printing the list of
ssh keys by setting
DONT_PRINT_SSH_KEY_LIST in a file in
.zshrc included in this kit will automatically source any files it finds in
~/.zshrc.d. This is to make it easy for you to add extra functions and aliases without having to maintain a separate fork of this repository, and also allows you to configure behavior of some of the plugins by setting environment variables.
The files in
.zshrc.d will be sourced in alphanumeric order after loading all the plugins and I suggest you use a naming scheme of
002-something-else etc to ensure they're loaded in the order you expect.
Make a file in
~/.zshrc.d named something like
999-reset-aliases. Since those are loaded after all the ZSH plugins, you can add lines like
unalias xyzzy to remove an alias named
xyzzy. Once you've cleared all the aliases you don't want, you can add new ones with the names you prefer.
The quickstart kit does an opinionated (i.e. my way) setup of ZSH options and adds some functions and aliases I like on my systems. However,
~/.zshrc.d is processed after the quickstart sets its aliases, functions and ZSH options, so if you don't care for something as set up in the quickstart, you can override the offending item in a shell fragment file there.
The quickstart kit will automatically check for updates every seven days. If you want to change the interval, set
QUICKSTART_KIT_REFRESH_IN_DAYS in a file in
~/.zshrc.d. If you want to disable self updating entirely, add
unset QUICKSTART_KIT_REFRESH_IN_DAYS in a file in
I've included what I think is a good starter set of zsh plugins in this repository. However, everyone has their own preferences for their environment.
To make the list easier to customize without having to maintain a separate fork of this kit, if you create a file named
.zshrc from this starter kit will source that instead of running the
load-starter-plugin-list function defined in
~/.zgen-local-plugins is not additive, it will completely replace the kit-provided list of plugins.
I know that it's a pain to create
.zgen-local-plugins from scratch, so to make customizing your plugins easier, I've included a
.zgen-local-plugins-example file at the root of the repository that will install the same plugin list that the kit does by default that you can use as a starting point for your own customizations.
Copy that to your
$HOME/.zgen-local-plugins, change the list and the next time you start a terminal session you'll get your list instead of mine.
The quickstart automatically autoloads zmv. If you want to disable that, create a file named
.zsh-quickstart-no-zmv in your home directory.
If you don't want zgen to load the oh-my-zsh defaults, create
.zsh-quickstart-no-omz in your home directory.
You may want to reconfigure your prompt after using it. The quickstart uses the powerlevel10k theme, so you can reconfigure your prompt by running
I've had reports that sometimes you need to reset your completions after adding a new plugin.
rm ~/.zcompdump* compinit
You try to update the kit and you get an error similar to this:
From https://github.com/unixorn/zsh-quickstart-kit 0c5bad9..2064c6b master -> origin/master 755f689...e3f8677 switch-to-zgenom -> origin/switch-to-zgenom (forced update) Updating 0c5bad9..2064c6b error: Your local changes to the following files would be overwritten by merge: zsh/.zshrc Please commit your changes or stash them before you merge. Aborting
This happens when you edit a file provided by the quickstart kit, in this case,
.zshrc. This is annoying, and in order to let you customize your ZSH settings without having to maintain your own fork, the kit-provided
.zshrc will load any files it finds in
stow --target=/Users/YourUsername zsh in the top level of the repo, and stow printed the following error:
WARNING! stowing zsh would cause conflicts: * existing target is neither a link nor a directory: .zshrc All operations aborted.
Per @jefheaton, this is caused when trying to replace an existing
.zshrc file. He fixed it by closing
~ in Finder so Finder wouldn't create a
.DS_Store file, deleting the existing
.DS_Store, and then removing the old
.zshrc. You may have to rename it first if ZSH is keeping the file open, then deleting it after closing all your Terminal/iTerm 2 windows.
dotfiles.github.io/ has a lot of great resources for dotfiles - frameworks for managing them, configurations for editors and other bootstraps with initial configurations to start from.
If you're using vim, spf13 is an excellent starter configuration and plugin collection.