Skip to content

Instantly share code, notes, and snippets.

Last active March 12, 2023 21:45
What would you like to do?
My setup guide for installing Cgywin, Mintty, Cmder, and ZSH.

What's this?

Instructions to obtain ZSH on a windows environment, without the input funny business presented by some other attempted solutions.

The final result is ZSH running on a mintty terminal, emulated by cygwin, and being handled by the popular cmder.

Why is this here?

For the benefit of myself and others. I've already followed these instructions twice. It took me hours to figure all this out, maybe someone else can save a few.

What exactly is covered?

  • Installing and setting up cmder
  • Installing and setting up cygwin with a package manager
  • Configuring Mintty colors, fonts, and a few other settings
  • Installing zsh, oh-my-zsh, a nifty plugin, and adding a color theme.
  • Configuring the usage of Dir_colors (albeit not in detail), as well as powerline fonts for fancy symbols
  • [optional] Generating a fancy promptline using a vim plugin (since I use vim)
  • Correcting input issues popular python, nodejs, and other language libraries may face... in a very simple way.

The Instructions:

While there is a lot of detail here, the ETA to follow these instructions with reasonable pace is ~1hr, especially if you skip a lot of the vim / dir_colors / extra plugin stuff (or save it for another time). I tried to present this in a way that covers the essentials first and cosmetics later.

1. Cygwin setup:

  1. This is straight forward and simple. Download Cygwin.
  2. Run the installer. When it asks for packages, search for 'wget' and make sure that it is selected for install (it will have a version number displayed when set to). Only download the bin, no need for src.
  3. Finish installing. Launch the cygwin terminal from the start menu or the batch file from C:\cygwin64

We're going to setup a package manager for cygwin now. Normally if you wanted more packages you'd have to re-run the installer - which means you have to keep it around for later. I don't like that option, so I found apt-cyg. Works like it sounds: apt-get for cygwin!

  1. Run the following to download apt-cyg with wget, install it into the bin of cygwin, and then install a few important commands. Note, you don't need gdb, vim, or dos2unix. I personally use all 3 and will be setting up vim, so I'm grabbing them now. Explore the cygwin packages and grab what you want! NOTE if you run into any line ending issues from here out, scroll down to "I can't run upgrade oh my zsh" and read
install apt-cyg /bin
apt-cyg install zsh git gdb dos2unix openssh vim [or your favorite text editor]
  1. If you want your home folder to be your user's folder, you need to edit /etc/nsswitch.conf. You can do this in the text editor you just downloaded, or type explorer /etc to open the root directory to edit the file in wordpad.
  2. Add this line to the bottom: db_home: windows

That's it for cygwin, you can close the terminal. Unless you are adding more packages with apt-cyg, you'll probably not be touching cygwin much more. It's mostly the backbone of this little operation. Now onto cmder, which is the terminal emulator of choice for this guide.

2. CMDER Setup:

  1. Download and install some or all of the powerline fonts. I only use Hack in this guide, so feel free to stick to this. Powerline fonts, for the uneducated, are patched fonts that include some fancy symbols related to git and such. You don't need this, but it's a plus!
  • "There's a install.ps1 in the folder. Set execution policy and run it." (Thanks @yiufung)
  1. Download cmder to get started (the full version!). This is a conemu derivative to run shells inside of. It's flexible and highly customizable, which tends to make it desireable. Features a quake-style drop down shell if you're that kind of person, but more importantly plays really nice with keyboard interactions.
  2. Unpack cmder to a desired location, this is where you'll be keeping cmder permenantly, so pick a cozy spot. Run cmder.exe.
  3. Right click the tab bar of cmder to open the settings. We're going to tweak a few things. Tweak as you like of course.
    1. Under Main (Check General > Fonts if missing - Thanks @SturmB!) we're going to set the font for non-mintty terminals, just for consistency: Hack, Size 16, Uncheck the option for an alternative font.
    2. Under Size&Position we're going to tweak the size of the final window. This applies for the quake style drop down too, which I'm going to lead you into setting up. Set width to 95%, height 75% (be sure to type the %!).
    3. Under Quake, make sure it's turned on!
    4. Under Confirm, turn off the new console / tab dupping confirms. Personally, I don't like them.
    5. IMPORTANT If anything, don't skip this setting: under Tasks, hit the '+' button to create a task that looks like this:
    Name:             Zsh::cygwin-mintty (or whatever you like)
    Task Paramaters:  -icon "C:\cygwin64\Cygwin.ico" (or blank, if you want to leave the icon be)
    Commands:         C:\cygwin64\bin\mintty.exe /usr/bin/zsh --login -i -new_console:d:%USERPROFILE%
    1. Under Keys and Macros, here are my settings. Tweak as you like:
    Win+Esc:    minimize/restore for quake
    Win+Down:   Create new console
    Win+Left:   Switch previous console
    Win+Right:  Switch next console
    1. Under Keyboard check "Install keyboard hooks" (Might now be called Support special hotkeys if missing - Thanks @SturmB!)
    2. Under Paste make sure each mode is in "Multi-line". This only affects cmd / non-mintty terminals from what I've seen, but is pleasent to have set for when not using mintty.
  4. Save settings and hit Win+Down, run your task. Tada you have a ConEmu running cygwin, running mintty. Wonderful. This is what we'll be using to tweak from here out! If you're prompted to generate configuration files, feel free to. If you keep following, I'll be providing my configuration which you can poke around. We're also about to overwrite the default .zshrc with the oh-my-zsh one, so hold out on tweaking that!

3. Setting up oh-my-zsh and plugins

You're already running zsh, but now we're going to add a manager to handle plugins, updating, and themes. Not the most critical stuff, but this is the reason I went through all this trouble - might as well pay it off!

  1. Install oh-my-zsh the manual way. This is well down the page under Advanced Topics. Here's my summary:
git clone git:// ~/.oh-my-zsh
cp ~/.oh-my-zsh/templates/zshrc.zsh-template ~/.zshrc
  1. Close the current terminal and open a new one to load up oh-my-zsh. If it prompts you to update, do it.
  2. If you have a theme file and a .zshrc, now is the time to copy that over (~/.zshrc and ~/.oh-my-zsh/themes/). You can find mine on my GitHub if you would like a starting point.
    • Realize it does a few things like source a dir_colors file, add ssh keys on login, adds the vim generated promptline, and utilize my personal theme (also in that repo). (It's also subject to change!) Be sure to follow step 6 or remove the related lines from the .zshrc if you use mine!
    • Alternatively, feel free to also just edit the .zshrc generated by oh-my-zsh and pick a theme from one of the defaults for yourself! Oh-my-zsh provides samples online, google it.
  3. Install any oh-my-zsh plugins now. More information on the repo! My favorite is zsh-syntax-highlighting. If you would like that plugin, follow the link and install with the oh-my-zsh package manager guide. Quick tip: This plugin only works if it is loaded last in your .zshrc's plugins list. Yes, I know, how odd.

4. Mintty settings

This one's short, but this is where we configure mintty's cursor, font, and other stuff. Feel free to poke around.

  1. Right click inside your terminal.
  2. Hit options.
  3. Under text change the font to 'Hack' (or your powerline font of choice). Choose your font size (I like 9).
  4. When you're done poking around the rest of the settings (like cursor), hit Apply and Save.

5. Fixing input issues for python, node, and friends.

I had issues using input libraries from NodeJS and such. I was confused how Git Bash was able to function just fine, yet mintty was failing. The trick? Git Bash aliases node, python, and others to use winpty. Follow along to install winpty and setup the aliases. If you want more information, be sure to stop and read the repo!

  1. Download the release from here:
  2. cd <path-to-extracted-files>
  3. Copy the needed files for installing: cp -an ./bin/* /usr/bin/. and cp -an ./lib/* /usr/lib/.
  4. Set permissions for the files with winpty at the start: chmod 755 /usr/bin/winpty* and chmod 755 /usr/lib/winpty*
  5. Ensure you have alias'd in your .zshrc: "node = winpty node.exe"
    • Repeat for any other problematic programs like: ipython php php5 psql python2.7
    • If you want to see how and what GitBash does it this for, go to your cmder's install directory and open: vendor\git-for-windows\etc\profile.d\

6. Dir Colors, Vim, and the fancy promptline

This section is not very detailed as we're now talking about aesthetic stuff. Look at my github for my configuration files and tweak as you like. Make sure you add in the needed references inside your .zshrc, like using dir_colors and sourcing the prompt line's .sh file. This is what I'm doing with them:

  1. Copy your minttyrc and dir_colors files into their needed spots (see my github for examples, or google!): ~/.minttyrc and ~/.dir_colors
  2. Copy your vimrc into ~/.vimrc and install vundle: git clone ~/.vim/bundle/Vundle.vim
  3. Launch vim and run :PluginInstall followed by :PromptlineSnapshot ~/ airline to generate the nifty looking powerline prompt script (this needs to be sourced in .zshrc).

I can't run upgrade_oh_my_zsh

I ran into this once, and it was due to line endings being in dos instead of unix. This may have been because of a gitconfig setting or an issue with the repo -- I'm going to say it was me. If you run into line ending issues for anything, try this:

  1. Verify this is the issue by checking the file format. For upgrade_oh_my_zsh this means the issue is inside ~/.oh-my-zsh/tools/
    • I do this by opening the file in vim, where the filetype is displayed on the powerline. If the type is utf-8[dos], you got carriage returns (not desired here).
  2. Install dos2unix (man page) with apt-cyg install dos2unix. This is a simple utility to convert the line endings of a file.
  3. To convert a file just run dos2unix <path to file>. In this case, dos2unix ~/.oh-my-zsh/tools/
Copy link

Thanks for this guide, I appreciate it!

/etc/nssswitch.conf => /etc/nsswitch.conf

Copy link

dfontana commented Jun 9, 2018

Fixed, thanks!

Copy link

On step 2 though, there are no instructions for Windows on how to install the fonts...

Copy link

yiufung commented Jul 5, 2018

@Panzerbjrn There's a install.ps1 in the folder. Set execution policy and run it.

Copy link

Cloning ohmyzsh and copying .zshrc does not install zsh for me. There must be a step im missing! Did you edit cmder settings to point to a zsh executable?

git clone git:// ~/.oh-my-zsh
cp ~/.oh-my-zsh/templates/zshrc.zsh-template ~/.zshrc

Copy link

SturmB commented Jan 16, 2019

I'm afraid I'm having trouble with Step 5: Fixing input issues...

  1. Download the release from here:
  2. cd
  3. Copy the needed files for installing: cp -an ./bin/* /usr/bin/. and cp -an ./lib/* /usr/lib/.

I've downloaded the repository and extracted to the root of my C: drive. Navigating to it (using a weird /cygdrive/c/winpty-master location), I do not see any bin/ nor lib/ folder, so the copy commands do not work.


What am I doing wrong?

Copy link

SturmB commented Jan 16, 2019

Also, you make several references to your GitHub repo for a starter .zshrc, theme, dir_colors, etc. A link to said repo (or even directly linking to the files you mention) would be a great help, since I don't see any of your repos that immediately jump out at me as the one containing such files.

Copy link

SturmB commented Jan 16, 2019

A few other minor issues that cropped up for me:

Section 2

5. Under Main we're going to set the font for non-mintty terminals, just for consistency: Hack, Size 16, Uncheck the option for an alternative font.

I'm afraid Main doesn't exist in Cmdr's Settings (maybe it did in the past). You'll now find the needed settings under General > Fonts.

Section 2

7. Under Keyboard check "Install keyboard hooks"

This setting appears to have been renamed to Support special hotkeys.

Section 4

3. Under text change the font to 'Hack' (or your powerline font of choice). Choose your font size (I like 9).

Unless I did something wrong when installing the Powerline fonts, "Hack" does not show up in the list of fonts for Mintty. It does appear in Cmdr's Settings > General > Fonts for changing the Main console font, but not in Mintty's [right click] > Options... > Text.

I suppose I could have forked this, fixed the errors, then created a pull request, but I still feel like too much of a newbie to be comfortable doing that.

Copy link

Just seconding @SturmB. This is a great guide and I've got my terminal finally running on Windows the same as on Linux thanks to your work, but there are a few tweaks that tripped me up for a second. Sturm covered most of them. :)

Copy link

mknooihuisen commented Apr 29, 2019

I'm afraid I'm having trouble with Step 5: Fixing input issues... What am I doing wrong?

In case @SturmB or anyone else has this problem (as I did). It isn't super clear, but you need to download a release asset from the github page else build winpty yourself using the readme file instructions. Extracting the release or building the project will produce the lib and bin folders referenced.

Copy link

dfontana commented Jul 4, 2019

Thanks for the feedback folks! I don't get notifications when this post sees comments (for some reason; I am subscribed... I'll try toggling it). Edit: Ha! The timing isn't to far off, but here was why

I appreciate the details provided - I've updated the main post to integrate your suggestions and updates.

I don't use windows as my main development environment any more! I swapped to WSL some time ago (highly recommend it if you haven't tried it and can). Even then, the integration with editors and such was lacklustre. I recently (< 2 weeks) decided to give Linux yet another go as a full time "personal" OS and have found success with all the apps I care for. That said, WSL is very compelling, especially after VSCode got a better WSL integration

Copy link

Hi, thanks for the guide! I'm having a problem with step 3, oh-my-zsh. I already had cmder installed before I installed cygwin, and I was using the git for Windows client that comes with it. So I skipped installing git from cygwin on step 1.4 and it appears that my version of git behaves differently than the one coming from cygwin, in that it treats my home directory (~) as the one under /cygdrive/c and not the actual one in the Windows users folder.
I guess if people follow your steps exactly will not have this issue, but I'm writing this just in case anybody does the same.
I had to manually copy the cloned files to the correct folder for now.

Copy link

SturmB commented Oct 22, 2019

Hey, @dfontana, I'm considering the move to WSL (especially since WSL2 promises to be much better when it's released), but there are a couple of concerns I have about it; mayhaps you could help allay them?:

  1. Is there a way to run WSL similarly to Cmder, in that the window could have a "Quake-style" dropdown from off-screen with a simple Win+Esc keystroke? I really like the convenience of that and would appreciate a similar convenience with WSL.
  2. Can it run zsh and oh-my-zsh, including in VSCode's integrated terminal?

Copy link

1. Is there a way to run WSL similarly to Cmder, in that the window could have a "Quake-style" dropdown from off-screen with a simple Win+Esc keystroke? I really like the convenience of that and would appreciate a similar convenience with WSL.

You should still be able to use Cmder! In the main post here that's what I was setting up: Cmder using Mintty to run WSL. You can probably skip the mintty mumbo jumbo at this point; I found in the early days it was helping solve some funky behavior I had encountered (inputs behaving weird, etc). I'm pretty sure its gotten better since then

2. Can it run zsh and oh-my-zsh, including in VSCode's integrated terminal?

It's a normal ubuntu installation! You can run pretty much anything; could run an X server if you wanted and use a terminal GUI program through that if you really felt inclined. Zsh is just a shell, so yes it can - that's what I spoke about. The VSCode integration with WSL has gotten even better, it works pretty naturally at this point. I used it for a brief stint without much of a hitch.

All that said, I haven't really been working with WSL much as of late; I do some one-off work every now and then using Hyper as my emulator for running WSL+ZSH. But most my work either occurs on MacOS or on my linux partition 🤷‍♂️

Copy link

Did everything under instruction, but wget gives the following error:

$ wget
--2021-03-07 18:57:51--
Resolving (,, 2606:4700:3032::6815:3fb8, ...
Connecting to (||:80... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: [following]
--2021-03-07 18:57:51--
Connecting to (||:443... connected.
GnuTLS: Error in the pull function.
Unable to establish SSL connection.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment