Setting Up Zsh on Windows with Cygwin

Zsh (Z shell) is a Unix shell that offers features like auto-completion, syntax highlighting, and customizable themes. While it’s commonly used on Linux and macOS, you can also set it up on Windows using Cygwin.

This guide covers how to set up Zsh on Windows and integrate it with VS Code.

Why Zsh on Windows?

Windows has come a long way with terminals, WSL exists but it runs in a separate Linux environment. Sometimes you want a Unix-like shell that works directly with your Windows filesystem without the overhead of a virtual environment.

Cygwin provides a POSIX-compatible environment that runs natively on Windows, giving you access to Unix tools including Zsh while maintaining direct access to your Windows files and programs.

Prerequisites

Before we start, make sure you have:

Windows 10 or 11
Administrator access to install software
VS Code installed (optional, but recommended)

Step 1: Install Cygwin

Download the Cygwin installer from cygwin.com
Run setup-x86_64.exe as Administrator
Choose “Install from Internet”
Select your installation directory (default is C:\cygwin64)
Choose a mirror site close to your location
In the package selection screen, search for and select these packages:
- zsh - The Z shell
- git - Version control (useful for Oh My Zsh)
- curl or wget - For downloading scripts
- nano or vim - Text editors

💡 Tip: Click "Skip" next to each package to cycle through versions until you see the version number you want to install.

Complete the installation

Step 2: Configure Zsh as Default Shell

After installation, open Cygwin Terminal and run:

# Check if zsh is installed
which zsh

# Set zsh as your default shell
chsh -s /bin/zsh

If chsh doesn’t work, you can manually edit /etc/passwd:

nano /etc/passwd

Find your user line and change /bin/bash to /bin/zsh. Save and exit.

Step 3: Install Oh My Zsh (Optional)

Oh My Zsh is a community-driven framework for managing Zsh configuration:

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

This will:

Install Oh My Zsh to ~/.oh-my-zsh
Create a .zshrc configuration file
Set a default theme (robbyrussell)

Customize Your Theme

Edit your .zshrc to change themes:

nano ~/.zshrc

Find the ZSH_THEME line and change it:

ZSH_THEME="agnoster"  # Theme with git integration
# or
ZSH_THEME="powerlevel10k/powerlevel10k"  # Configurable theme

For Powerlevel10k, you’ll need to install it first:

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

Step 4: Configure VS Code

Now let’s integrate Cygwin Zsh with VS Code. Open your VS Code settings (Ctrl+,) and click the JSON icon in the top right, or press Ctrl+Shift+P and search for “Preferences: Open User Settings (JSON)“.

Add the following configuration:

{
    "terminal.integrated.profiles.windows": {
        "Cygwin Zsh": {
            "path": "C:\\cygwin64\\bin\\zsh.exe",
            "args": ["-l"],
            "icon": "terminal-bash",
            "env": {
                "CHERE_INVOKING": "1"
            }
        }
    },
    "terminal.integrated.defaultProfile.windows": "Cygwin Zsh"
}

Understanding the Configuration

Property	Description
`path`	Points to the Zsh executable in your Cygwin installation
`args: ["-l"]`	Starts Zsh as a login shell, loading your `.zprofile` and `.zshrc`
`icon`	The icon displayed in the terminal dropdown
`CHERE_INVOKING`	Tells Cygwin to start in the current directory instead of home

Step 5: Fix Common Issues

Issue: Terminal starts in wrong directory

Add this to your .zshrc:

# Start in the directory VS Code opened
if [[ -n "$CHERE_INVOKING" ]]; then
    unset CHERE_INVOKING
    cd "$PWD"
fi

Issue: Colors or themes not displaying correctly

Install a Nerd Font that supports special characters:

Download a font from nerdfonts.com (e.g., “MesloLGS NF”)
Install the font on Windows
Add to your VS Code settings:

{
    "terminal.integrated.fontFamily": "MesloLGS NF"
}

Issue: Windows paths with spaces

Cygwin translates Windows paths. Use cygpath to convert:

# Convert Windows path to Cygwin path
cygpath "C:\Program Files"
# Output: /cygdrive/c/Program Files

# Convert Cygwin path to Windows path
cygpath -w /home/username
# Output: C:\cygwin64\home\username

Useful Plugins

Oh My Zsh comes with many plugins. Enable them in .zshrc:

plugins=(
    git                     # Git aliases and functions
    zsh-autosuggestions     # Fish-like autosuggestions
    zsh-syntax-highlighting # Syntax highlighting
    z                       # Jump to frequently used directories
)

For plugins not included by default:

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

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

Final `.zshrc` Example

Here’s a basic configuration example:

# Path to Oh My Zsh
export ZSH="$HOME/.oh-my-zsh"

# Theme
ZSH_THEME="agnoster"

# Plugins
plugins=(git z zsh-autosuggestions zsh-syntax-highlighting)

# Load Oh My Zsh
source $ZSH/oh-my-zsh.sh

# Custom aliases
alias ll="ls -la"
alias cls="clear"
alias projects="cd /cygdrive/d/code"

# Fix for VS Code directory
if [[ -n "$CHERE_INVOKING" ]]; then
    unset CHERE_INVOKING
fi

Git Authentication with GitHub CLI

If you have GitHub CLI (gh) installed on Windows and want to use it with Cygwin Git, you might encounter authentication errors like:

'C:\Program Files\GitHub CLI\gh.exe' auth git-credential get: line 1: C:\Program Files\GitHub CLI\gh.exe: command not found
fatal: Authentication failed

This happens because Cygwin Git tries to use Windows paths that don’t work in the Cygwin environment.

Solution: Configure Git to Use GitHub CLI

First, verify that gh is accessible in Cygwin:

which gh
# Should output: /cygdrive/c/Program Files/GitHub CLI/gh

If you’re not already authenticated, log in with GitHub CLI:

gh auth login

Then configure Git to use gh as the credential helper:

# Remove any broken credential helpers
git config --global --unset-all credential.helper

# Set gh as the credential helper
git config --global credential.helper '!gh auth git-credential'

Verify the configuration:

git config --global --list | grep credential
# Should show: credential.helper=!gh auth git-credential

Now Git operations will authenticate through GitHub CLI automatically:

git push  # Works without prompting for credentials

Alternative: Use Personal Access Token

If you prefer not to use GitHub CLI:

# Use Git's built-in credential storage
git config --global credential.helper store

# Next time you push, enter your username and Personal Access Token
git push

Create a Personal Access Token at github.com/settings/tokens with repo scope.

Conclusion

With these steps, you should have Zsh running on Windows through Cygwin, with optional Oh My Zsh configuration for themes and plugins. The VS Code integration allows you to use this shell directly in your editor.

Cygwin tools work alongside your Windows programs, so you can use both Unix and Windows commands as needed.

Troubleshooting

Q: Zsh is slow to start A: This is often caused by too many plugins. Comment out plugins one by one to find the culprit. You can also add cygwin folder to windows defender exclusion list.

Q: Some commands don’t work A: Make sure the required packages are installed via Cygwin setup. Run the installer again to add packages.

Q: Git shows wrong line endings A: Configure git for Windows:

git config --global core.autocrlf input

Tags:

windows zsh terminal vscode cygwin

Back to Blog

Previous Understanding How Computer Calculate Mathematical Equation