WSL is the best way to work on Windows.

Follow along to setup WSL and Z shell, an alternative to bash with awesome plugin & theme support. This setup uses the popular Oh My Zsh Zsh configuration framework to manage Zsh plugins and themes (it comes bundled with helpers & aliases as well). As for the theme, we use the impressive, Powerlevel10k seen in the screenshot above.

You can find this tutorial and referenced files on github at deanbot/easy-wsl-oh-my-zsh-p10k.

Table of contents

  1. WSL and Ubuntu
    1. Enable features for WSL and WSL 2
    2. Install Ubuntu
  2. VS Code
  3. Windows Terminal
    1. Install Windows Terminal
    2. Update default profile
    3. Configure Windows Terminal
  4. Zsh and Oh My Zsh
    1. Install and setup Zsh
    2. Install Oh My Zsh
  5. Powerlevel10k
    1. Install fonts
    2. Install theme
    3. Run configuration wizard
    4. Enable battery indicator
  6. Install Zsh plugins
  7. Next steps
  8. Revert to bash

WSL and Ubuntu

First let’s set about installing WSL and the latest LTS of Ubuntu.

Enable features for WSL and WSL 2

  1. Run Windows PowerShell as administrator
  2. Install WSL via: dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Microsoft note: “WSL 2 is only available in Windows 10, Version 2004, Build 19041 or higher. You may need to update your Windows version.”

To upgrade to WSL 2:

  1. Enable the required feature via: dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
  2. Restart your machine.
  3. Download and install the WSL 2 Linux kernel update.
  4. Open Windows PowerShell and run the command: wsl --set-default-version 2

Install Ubuntu

To install the latest Ubuntu LTS version (i.e. 20.04):

  1. Open Windows Store and search for Ubuntu (quick link). Select Ubuntu (note you can verify the Ubuntu version by selecting More) and then select Install.

  2. Launch Ubuntu to complete installation.

  3. Create a user account by entering a User Name, i.e. your first name (typically lowercase) and a password.

    See also: Change or recover your password

  4. Update packages enter: sudo apt update && sudo apt upgrade

    Note you may need to right click or ctrl+shift+v to paste.

    Press [enter] to select Y at the prompt to install any package updates.

We’ll switch to Windows Terminal in a following step, as the default WSL/Ubuntu terminal emulator is not the greatest.

VS Code

If you’re a VS Code user, some light setup is required for proper WSL use.

After installing WSL, launch VS Code. It should prompt you to install Remote - WSL. Alternatively, install the Remote Development extension pack which bundles a few related extensions.

See also: VS Code: Developing in WSL

Windows Terminal

I highly recommend installing Windows Terminal. The most compelling reason might be how easy it is to launch different shells be they PowerShell, WSL, git bash, or command prompt… but it can split/resize/move between panes really well too.

Install Windows Terminal

To install Windows Terminal, open Windows Store. Search for and install Windows Terminal. I suggest pinning Windows Terminal to your start menu or taskbar.

Update default profile

The default profile shown when you launch Windows Terminal is Windows PowerShell. Selecting the dropdown reveals Ubuntu.

To change the default profile:

  1. Enter ctrl+, to open the settings file for Windows Terminal in you default editor.
  2. Locate the guid for WSL/Ubuntu and then copy and paste this value in the defaultProfile property.

Configure Windows Terminal

Note: See settings.json for reference.

  1. Include the following settings for profiles.defaults:

     "defaults": {
         // Put settings here that you want to apply to all profiles.
         // "fontFace": "MesloLGS NF",
         "fontSize": 9,
         "snapOnInput": true,
         "historySize": 9001,
         "acrylicOpacity": 0.85,
         "useAcrylic": true,
         "closeOnExit": true
     },

    Leave fontFace commented until you install the font in a following section.

  2. Hide irrelevant profiles by setting the hidden property to true.

  3. To start in linux home instead of windows user profile directory, add "startingDirectory" property to the Ubuntu profile and set it to "//wsl$/Ubuntu/home/<username>", replacing ‘Ubuntu’ with the name of the distribution you installed and and ‘’ with your Ubuntu username, i.e. if you installed ‘Ubuntu 20.0.4 LTS’, use "startingDirectory": "//wsl$/Ubuntu-20.0.4/home/<username>".

Zsh and Oh My Zsh

Next, we’ll install Zsh and Oh My Zsh.

Install and setup Zsh

To install Z shell and set it as your default shell run:

sudo apt install zsh
chsh -s /bin/zsh

Log out and login back again to use your new default shell.

If you have no .zsh[...] files in your home directory you will be prompted. Feel free to run through the configuration wizard however this will get replaced by Oh My Zsh. I recommend selecting 2 at the prompt to create a .zshrc with defaults.

Install Oh My Zsh

To install Oh My Zsh run:

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

If you had a .zshrc file it’s now backed up as .zshrc.pre-oh-my-zsh and replaced with a new configuration file which loads Oh My Zsh.

Powerlevel10k

Next, we’ll install the Powerlevel10k Zsh theme. The recommended font for p10k works well in Windows Terminal.

Install fonts

First, manually install the recommended Meslo Nerd Font (patched for p10k) - found here.

To install, download and double-click each variation and select install.

Note: If using Windows Terminal, enable the font by adding "fontFace": "MesloLGS NF" to profile.defaults or the WSL profile.

Install theme

To install p10k:

  1. Run: git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/themes/powerlevel10k
  2. Set ZSH_THEME="powerlevel10k/powerlevel10k" in ~/.zshrc.

Run configuration wizard

Restart your shell by logging out logging back in. The configuration wizard should start automatically, otherwise run p10k configure.

Follow prompts to configure p10k to your liking. First, it prompt you to verify whether you see given icons. Afterwards, you’ll be prompted for ui preferences. These are up to you. The following choices work well but go crazy.

  • Prompt Style: Rainbow
  • Character Set: Unicode
  • Show Current Time: 24-hour format
  • Prompt Separators: Slanted
  • Prompt Heads: Sharp
  • Prompt Tails: Flat
  • Prompt Height: Two Lines
  • Prompt Connection: Solid
  • Prompt Frame: Left
  • Connection & Frame Color: Dark
  • Prompt Spacing: Sparse
  • Icons: Many Icons
  • Prompt Flow: Concise
  • Enable Transient Prompts: yes
  • Instant Prompt Mode: Verbose

If you don’t like what you came up with restart or remove your .p10k.zsh file.

Note: see p10k.zsh for reference.

The configuration I’m using at any given time is found in my deanbot/dotfiles repo.

Enable battery indicator

  1. Edit .p10k.zsh
  2. Uncomment the battery # internal batter line in the list of POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS and save.
  3. Run: source ~/.p10k.zsh to see changes.

Install Zsh Plugins

Most plugins are installed automatically with Oh My Zsh by editting plugins in .zshrc.

The following suggested plugins have minimal installation steps:

To install zsh-autosuggestion and zsh-syntax-highlighting:

  1. Run the following commands one at a time:
git clone https://github.com/zsh-users/zsh-autosuggestions.git $ZSH_CUSTOM/plugins/zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git $ZSH_CUSTOM/plugins/zsh-syntax-highlighting
  1. Permissions on these two plugins may be too permissive (you’ll be warned by zsh the next time you log into your shell). To correct this run:

     cd $ZSH_CUSTOM/plugins/
     sudo chmod 755 ./zsh*
     cd ~
  2. Edit .zshrc via your preferred editor be it nano, micro, VSCode, etc (i.e. for VSCode code ~/.zshrc).

  3. update the plugins line to: plugins=(git z zsh-autosuggestions zsh-syntax-highlighting) and save.

Next steps

Where to go from here? Some suggestions in no particular order:

  • Review/adjust Windows Terminal keybindings.
  • Extend dot files with your desired aliases or path modifications.
  • Familiarize yourself with Zsh and browse tips & tricks from the community.
  • View the Oh My Zsh cheatsheet.
  • Explore the Oh My Zsh plugins directory.
  • Customize p10k.

Revert to Bash

So you want to cut and run aye? Returning to a bash shell is easily done:

  1. Uninstall Oh My Zsh (ref): uninstall_oh_my_zsh
  2. Set default shell to bash: chsh -s $(which bash)

Last updated