{
	"id": "83793a00-fec8-49ec-b617-425293b15c6e",
	"created_at": "2026-04-06T00:14:16.820268Z",
	"updated_at": "2026-04-10T03:22:09.824864Z",
	"deleted_at": null,
	"sha1_hash": "300f933e2e86d7fa35f7b649f3ed7889efa585f7",
	"title": "Moving to zsh, part 2: Configuration Files",
	"llm_title": "",
	"authors": "",
	"file_creation_date": "0001-01-01T00:00:00Z",
	"file_modification_date": "0001-01-01T00:00:00Z",
	"file_size": 106924,
	"plain_text": "Moving to zsh, part 2: Configuration Files\r\nBy Published by ab Mac Admin, Consultant, and Author View all posts by ab\r\nPublished: 2019-06-18 · Archived: 2026-04-05 21:26:08 UTC\r\nApple has announced that in macOS 10.15 Catalina the default shell will be zsh .\r\nIn this series, I will document my experiences moving bash settings, configurations, and scripts over to zsh .\r\nPart 1: Moving to zsh\r\nPart 2: Configuration Files (this article)\r\nPart 3: Shell Options\r\nPart 4: Aliases and Functions\r\nPart 5: Completions\r\nPart 6: Customizing the zsh Prompt\r\nPart 7: Miscellanea\r\nPart 8: Scripting zsh\r\nThis series has grown into a book: reworked and expanded with more detail and topics. Like my other\r\nbooks, I plan to update and add to it after release as well, keeping it relevant and useful. You can order\r\nit on the Apple Books Store now.\r\nIn part one I talked about Apple’s motivation to switch the default shell and urge existing users to change to zsh .\r\nSince I am new to zsh as well, I am planning to document my process of transferring my personal bash setup\r\nand learning the odds and ends of zsh .\r\nMany websites and tutorials leap straight to projects like oh-my-zsh or prezto where you can choose from\r\nhundreds of pre-customized and pre-configured themes.\r\nWhile these projects are very impressive and certainly show off the flexibility and power of zsh customization, I\r\nfeel this will actually prevent an understanding of how zsh works and how it differs from bash . So, I am\r\nplanning to build my own configuration ‘by hand’ first.\r\nAt first, I actually took a look at my current bash_profile and cleaned it up. There were many aliases and\r\nfunctions which I do not use or broke in some macOS update. I the end, this is what I want to re-create in zsh :\r\naliases\r\nmostly shortcuts to open files with a specific application\r\nfunctions\r\nshow man pages in a dedicated Terminal window\r\nsome more simple functions\r\nget the frontmost Finder window path\r\nshell settings\r\nhttps://scriptingosx.com/2019/06/moving-to-zsh-part-2-configuration-files/\r\nPage 1 of 5\n\ncase-insensitive globbing\r\ncase-insensitive path-completion (for bash this is set in .inputrc )\r\ncommand history, shared across windows and sessions\r\nuse BBEdit as the editor\r\nprompt:\r\nshow current working dir\r\nshow a colored symbol showing the last command’s exit code\r\nupdate the Terminal window title bar to show the cwd\r\nMost of these should be fairly easy to transfer. Some might be… interesting.\r\nBut first, where do we put our custom zsh configuration?\r\nbash has a list of possible files that it tries in predefined order. I have the description in my post on the\r\nbash_profile .\r\nzsh also has a list of files it will execute at shell startup. The list of possible files is even longer, but somewhat\r\nmore ordered.\r\nall users user login shell interactive shell scripts Terminal.app\r\n/etc/zshenv .zshenv √ √ √ √\r\n/etc/zprofile .zprofile √ x x √\r\n/etc/zshrc .zshrc x √ x √\r\n/etc/zlogin .zlogin √ x x √\r\n/etc/zlogout .zlogout √ x x √\r\nThe files in /etc/ will be launched (when present) for all users. The .z* files only for the individual user.\r\nBy default, zsh will look in the root of the home directory for the user .z* files, but this behavior can be\r\nchanged by setting the ZDOTDIR environment variable to another directory (e.g. ~/.zsh/ ) where you can then\r\ngroup all user zsh configuration in one place.\r\nOn macOS you could set the ZDOTDIR to ~/Documents/zsh/ and then use iCloud syncing (or a different file\r\nsync service) to have the same files on all your Macs. (I prefer to use git .)\r\nbash will either use .bash_profile for login shells, or .bashrc for interactive shells. That means, when you\r\nwant to centralize configuration for all use cases, you need to source your .bashrc from .bash_profile or\r\nvice versa.\r\nzsh behaves differently. zsh will run all of these files in the appropriate context (login shell, interactive shell)\r\nwhen they exist.\r\nhttps://scriptingosx.com/2019/06/moving-to-zsh-part-2-configuration-files/\r\nPage 2 of 5\n\nzsh will start with /etc/zshenv , then the user’s .zshenv . The zshenv files are always used when they exist,\r\neven for scripts with the #!/bin/zsh shebang. Since changes applied in the zshenv will affect zsh behavior\r\nin all contexts, you should you should be very cautious about changes applied here.\r\nNext, when the shell is a login shell, zsh will run /etc/zprofile and .zprofile . Then for interactive\r\nshells  /etc/zshrc and .zshrc . Then, again, for login shells /etc/zlogin and .zlogin . Why are there two\r\nfiles for login shells? The zprofile exists as an analog for bash ’s and sh ’s profile files, and zlogin as an\r\nanalog for ksh login files.\r\nFinally, there are zlogout files that can be used for cleanup, when a login shell exits. In this case, the user level\r\n.zlogout is read first, then the central /etc/zlogout . If the shell is terminated by an external process, these\r\nfiles might not be run.\r\nApple Provided Configuration Files\r\nmacOS Mojave (and earlier versions) includes /etc/zprofile and /etc/zshrc files. Both are very basic.\r\n/etc/zprofile uses /usr/libexec/path_helper to set the default PATH . Then /etc/zshrc enables UTF–8\r\nwith setopt combiningchars .\r\nLike /etc/bashrc there is a line in /etc/zshrc that would load /etc/zshrc_Apple_Terminal if it existed.\r\nThis is interesting as /etc/bashrc_Apple_Terminal contains quite a lot of code to help bash to communicate\r\nwith the Terminal application. In particular bash will send a signal to the Terminal on every new prompt to\r\nupdate the path and icon displayed in the Terminal window title bar, and provides other code relevant for saving\r\nand restoring Terminal sessions between application restarts.\r\nHowever, there is no /etc/zshrc_Apple_Terminal and we will have to provide some of this functionality\r\nourselves.\r\nNote: As of this writing, /etc/zshrc in the macOS Catalina beta is different from the Mojave\r\n/etc/zshrc and provides more configuration. However, since Catalina is still beta, I will focus these\r\narticles on Mojave and earlier. Once Catalina is released, I may update these articles or write a new one\r\nfor Catalina, if necessary.\r\nWhich File to use?\r\nWhen you want to use the ZDOTDIR variable to change the location of the other zsh configuration files, setting\r\nthat variable in ~/.zshenv seems like a good choice. Other than that, you probably want to avoid using the\r\nzshenv files, since it will change settings for all invocations of zsh , including scripts.\r\nmacOS Terminal considers every new shell to be a login shell and an interactive shell. So, in Terminal a new\r\nzsh will potentially run all configuration files.\r\nFor simplicity’s sake, you should use just one file. The common choice is .zshrc .\r\nhttps://scriptingosx.com/2019/06/moving-to-zsh-part-2-configuration-files/\r\nPage 3 of 5\n\nMost tools you can download to configure zsh , such as ‘prezto’ or ‘oh-my-zsh’, will override or re-configure\r\nyour .zshrc . You could consider moving your code to .zlogin instead. Since .zlogin is sourced after\r\n.zshrc it can override settings from .zshrc . However, .zlogin is only called for login shells.\r\nThe most common situation where you do not get a login shell with macOS Terminal, is when you switch to zsh\r\nfrom another shell by typing the zsh command.\r\nI would recommend to put your configuration in your .zshrc file and if you want to use any of the theme\r\nprojects, read and follow their instructions closely as to how you can preserve your configurations together with\r\ntheirs.\r\nManaging the shell for Administrators\r\nMacAdmins may have the need to manage certain shell settings for their users, usually environment variables to\r\nconfigure certain command line tool’s behaviors.\r\nThe most common need is to expand the PATH environment variable for third party tools. Often the third party\r\ntools in question will have elaborate postinstall scripts that attempt to modify the current user’s .bash_profile\r\nor .bashrc . Sometimes, these tools even consider that a user might have changed the default shell to something\r\nother than bash .\r\nOn macOS, system wide changes to the PATH should be done by adding files to /etc/paths.d .\r\nAs an administrator you should be on the lookout for scripts and installers that attempt to modify configuration\r\nfiles on the user level, disable the scripts during deployment, and manage the required changes centrally. This will\r\nallow you to keep control of the settings even as tools change, are added or removed from the system, while\r\npreserving the user’s custom configurations.\r\nTo manage environment variables other than PATH centrally, administrators should consider /etc/zshenv or\r\nadding to the existing /etc/zshrc . In these cases you should always monitor whether updates to macOS\r\noverwrite or change these files with new, modified files of their own.\r\nSummary\r\nThere are many possible files where the zsh can load user configuration. You should use ~/.zshrc for your\r\npersonal configurations.\r\nThere are many tools and projects out there that will configure zsh for you. This is fine, but might keep you\r\nfrom really understanding how things work.\r\nMacAdmins who need to manage these settings centrally, should use /etc/paths.d and similar technologies or\r\nconsider /etc/zshenv or /etc/zshrc .\r\nApple’s built-in support for zsh in Terminal is not as detailed as it is for bash .\r\nNext: Part 3 – Shell Options\r\nhttps://scriptingosx.com/2019/06/moving-to-zsh-part-2-configuration-files/\r\nPage 4 of 5\n\nSource: https://scriptingosx.com/2019/06/moving-to-zsh-part-2-configuration-files/\r\nhttps://scriptingosx.com/2019/06/moving-to-zsh-part-2-configuration-files/\r\nPage 5 of 5",
	"extraction_quality": 1,
	"language": "EN",
	"sources": [
		"MITRE"
	],
	"references": [
		"https://scriptingosx.com/2019/06/moving-to-zsh-part-2-configuration-files/"
	],
	"report_names": [
		"moving-to-zsh-part-2-configuration-files"
	],
	"threat_actors": [],
	"ts_created_at": 1775434456,
	"ts_updated_at": 1775791329,
	"ts_creation_date": 0,
	"ts_modification_date": 0,
	"files": {
		"pdf": "https://archive.orkl.eu/300f933e2e86d7fa35f7b649f3ed7889efa585f7.pdf",
		"text": "https://archive.orkl.eu/300f933e2e86d7fa35f7b649f3ed7889efa585f7.txt",
		"img": "https://archive.orkl.eu/300f933e2e86d7fa35f7b649f3ed7889efa585f7.jpg"
	}
}