WSL Setup: Ubuntu, ZSH, Pyenv

Introduction

In this article, we’ll walk you through setting up WSL (Windows Subsystem for Linux) with Ubuntu, ZSH, and Pyenv. Whether you’re a software developer, data scientist, or just someone who prefers working in a Linux environment but needs to stick with Windows, WSL offers the best of both worlds. We’ll cover the benefits of using Ubuntu on WSL, set up ZSH as our shell for a more robust terminal experience, and use Pyenv to manage multiple Python versions efficiently.

Overview of WSL (Windows Subsystem for Linux)

WSL allows you to run a full Linux distribution directly within Windows, without the need for dual-booting or using virtual machines. It integrates deeply with Windows, allowing access to files, system resources, and even Windows applications. WSL2, the latest version, includes a full Linux kernel, improving performance and compatibility with Linux tools.

Benefits of using Ubuntu on WSL

Seamless Integration: You can run Linux commands alongside your Windows applications without switching environments.
Access to Linux tools: Developers can use their favorite Linux tools (like grep, awk, sed, etc.) directly in Windows.
Performance Boost: WSL2 improves performance by leveraging a real Linux kernel and providing better I/O operations.
Resource Efficiency: Compared to running a full virtual machine, WSL is lightweight and uses fewer resources.
Simplified Development: You can develop, test, and run Linux-based software (e.g., web apps, server-side applications) without leaving your Windows setup.

Introduction to ZSH and Pyenv

ZSH (Z Shell) is an extended version of the Bash shell, with many features that enhance productivity. It’s highly customizable, with themes, plugins, and advanced autocompletion.
Pyenv is a simple Python version management tool that allows you to switch between multiple Python versions easily. Whether you need Python 2.x, Python 3.x, or a specific version for a project, Pyenv makes it hassle-free

Prerequisites

Before diving into the setup, make sure you meet the following requirements:

Windows version compatibility

Windows 10 (version 1903 or higher) or Windows 11: WSL2 requires a specific Windows build. Ensure your Windows version is up to date.
- To check your version, press Win + R, type winver, and hit Enter.
If you're running an older version, update through Windows Update.

Enabling WSL on Windows

To install WSL, we first need to enable it as a feature in Windows.

Open PowerShell as Administrator:
- Press Win + X and choose "Windows PowerShell (Admin)".

Enable WSL Feature:

Run the following command to enable WSL:

  dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Enable Virtual Machine Platform:

This step is needed for WSL2. Run:

  dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart Your Computer:
- After enabling these features, reboot your machine for the changes to take effect.

Installing Ubuntu on WSL

Installing Ubuntu in Windows Terminal

Check Available WSL Distros:
- Open Command Prompt or PowerShell as Administrator and run:
```
  wsl --list --online
```
- This command lists all available Linux distributions, including different versions of Ubuntu.
Install Ubuntu:
- To install the latest version of Ubuntu (for example, Ubuntu 22.04 LTS), use the following command:
```
  wsl --install -d Ubuntu
```
- If you prefer a specific version (e.g., Ubuntu 20.04 LTS), specify it as:
```
  wsl --install -d Ubuntu-20.04
```

Initial setup and configuration

Once Ubuntu is installed, follow these steps to complete the setup:

Launch Ubuntu:
- After installation, launch Ubuntu by typing:
```
  wsl
```
Create a User Account:
- The first time Ubuntu runs, you'll be asked to create a new user account.
- Enter a username and password for the administrative user.

Updating and upgrading Ubuntu packages

Update and Upgrade Packages:
- After setting up your user account, update the package list and upgrade any installed packages:
```
  sudo apt update && sudo apt upgrade -y
```
Optional: Clean up unnecessary files:
```
  sudo apt autoremove
```

Installing and Configuring ZSH

Installing ZSH

Install ZSH:
- In your WSL terminal, run the following command to install ZSH:
```
  sudo apt install zsh -y
```
- This installs ZSH on your Ubuntu distribution.
Verify Installation:
- Once installed, check the ZSH version to verify it’s properly installed:
```
  zsh --version
```

Making ZSH the default shell

Change the Default Shell to ZSH:
- To make ZSH your default shell, use the following command:
```
  chsh -s $(which zsh)
```
- This command changes your default shell to ZSH for your user.
Log Out and Back In:
- Close your WSL terminal and reopen it. You should now be using ZSH as your default shell.

Introduction to Oh My Zsh

Oh My Zsh is a popular open-source framework that makes ZSH configuration much easier and more enjoyable by offering themes, plugins, and configuration templates.

Installing Oh My Zsh and themes/plugins

Install Oh My Zsh:

Run this command to install Oh My Zsh using curl:

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

You can also use wget if curl isn’t available:

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

Choose a Theme:
- Oh My Zsh comes with a variety of themes. The default theme is called robbyrussell, but you can change it in the ~/.zshrc file.
- Open the ZSH configuration file:
```
  nano ~/.zshrc
```
- Find the line that says ZSH_THEME="robbyrussell" and replace robbyrussell with another theme name like agnoster or powerlevel10k (if installed).
Enable Plugins:
- Oh My Zsh also supports plugins like git for Git integration. You can enable plugins by adding them to the plugins section of the ~/.zshrc file:
```
  plugins=(git)
```
- Save the file and reload ZSH:
```
  source ~/.zshrc
```

Basic ZSH configuration tips

utocomplete: ZSH has robust autocomplete capabilities. Start typing a command and press Tab to see suggestions.
Alias Commands: You can create custom command shortcuts (aliases) by adding them to your ~/.zshrc file. Example:
```
  alias ll="ls -la"
```
Customizing the Prompt: ZSH’s prompt can be customized for a personalized terminal appearance. This can be done by modifying the PS1 variable in your ~/.zshrc file.

Installing and Configuring Pyenv

Now that ZSH is up and running, let's set up Pyenv to manage Python versions efficiently in your WSL environment

Installing dependencies for Pyenv

Before installing Pyenv, we need to install the required dependencies:

Install Dependencies:

Run the following command to install the necessary packages for Pyenv:

  sudo apt update
  sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev \
  liblzma-dev python3-openssl git

Installing Pyenv

Install Pyenv:

Run this command to install Pyenv using Git:
```
  curl https://pyenv.run | bash
```
This script clones the Pyenv repository and sets up the necessary environment variables.

Setting up Pyenv in the shell

Add Pyenv to your shell startup file so it loads automatically every time a terminal session starts. Edit your ~/.zshrc file:
```
  nano ~/.zshrc
```

Add the following lines to the end of the file:

  export PATH="$HOME/.pyenv/bin:$PATH"
  eval "$(pyenv init --path)"
  eval "$(pyenv init -)"
  eval "$(pyenv virtualenv-init -)"

Save the file and reload your ZSH configuration:
```
  source ~/.zshrc
```

Installing Python versions using Pyenv

Install a Specific Python Version:
- To install a particular version of Python, use the following command (replace 3.9.7 with the version you need):
```
  pyenv install 3.9.7
```
View Installed Python Versions:
- To see the list of installed Python versions:
```
  pyenv versions
```

Setting global and local Python versions

Set Global Python Version (default for all projects):
```
  pyenv global 3.9.7
```
Set Local Python Version (specific to a project): Navigate to your project directory and run:
```
  pyenv local 3.9.7
```

Integrating ZSH with Pyenv

Now that Pyenv is set up, we’ll integrate it with ZSH to improve our shell experience.

ZSH plugins for Pyenv

Oh My Zsh has a built-in plugin for Pyenv. To enable it, add pyenv to the plugins list in your ~/.zshrc file:

plugins=(git pyenv)

Adding Pyenv initialization to ZSH configuration

If you haven't already done so during installation, make sure the following lines are in your ~/.zshrc to initialize Pyenv properly:

eval "$(pyenv init --path)"
eval "$(pyenv init -)"

Reload ZSH Configuration:

After making the changes, reload your ZSH session by running:
```
  bashCopy codesource ~/.zshrc
```

Common issues and troubleshooting

While setting up WSL, ZSH, and Pyenv, you might encounter some common issues. Here’s a list of potential problems and their solutions:

1. WSL Version Mismatch (Using WSL 1 Instead of WSL 2)

If you notice that your Linux distribution is running WSL 1 instead of WSL 2:

Check the current WSL version:
```
  wsl --list --verbose
```
- If it says "Version 1" next to your Ubuntu distribution, you’ll need to convert it to WSL 2.
Convert to WSL 2:
```
  wsl --set-version Ubuntu 2
```

2. `zsh` Not Defaulting to the Correct Shell After Restart

Sometimes after setting ZSH as your default shell, Ubuntu may still default to Bash.

Fix: Ensure ZSH is correctly set as the default shell by running:
```
  chsh -s $(which zsh)
```
Then, close and reopen the terminal.

3. Pyenv Command Not Found After Installation

If you’re unable to use Pyenv commands after installation, it’s likely that Pyenv isn’t correctly initialized in your shell.

Fix: Ensure you have the following lines in your ~/.zshrc file:

  export PATH="$HOME/.pyenv/bin:$PATH"
  eval "$(pyenv init --path)"
  eval "$(pyenv init -)"
  eval "$(pyenv virtualenv-init -)"

After adding these, reload the configuration:

  source ~/.zshrc

4. ZSH Autocomplete Issues

If ZSH autocompletion isn’t working as expected:

Fix: You might need to enable autocompletion by adding the following plugin to your ~/.zshrc:
```
  plugins=(git pyenv zsh-autosuggestions zsh-syntax-highlighting)
```
Then reload ZSH:
```
  source ~/.zshrc
```

5. Python Version Fails to Install in Pyenv

If you encounter errors while installing Python versions using Pyenv:

Fix: Ensure you’ve installed all the necessary dependencies:

  sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev \
  liblzma-dev python3-openssl git

If you’ve installed the dependencies and are still facing issues, try running:

  pyenv doctor

This will diagnose issues and give you specific suggestions to fix them.

6. WSL Network Issues

Sometimes, WSL may experience networking issues that prevent package installations or updates.

Fix: Restart WSL by running:
```
  wsl --shutdown
```
Then relaunch your WSL terminal.

With these troubleshooting tips, you should be able to resolve most common issues.

Conclusion

Congratulations! You’ve successfully set up WSL with Ubuntu, configured ZSH, and installed Pyenv to manage your Python versions. Here's a quick recap of the steps we covered:

Overview of WSL: We explored how to enable and install Ubuntu on WSL using the command line.
Installing and Configuring ZSH: You installed ZSH, set it as your default shell, and enhanced it with Oh My Zsh for themes and plugins.
Pyenv Setup: You installed Pyenv to manage multiple Python versions and integrated it smoothly with ZSH.
Troubleshooting: We addressed common issues, ensuring a seamless experience with WSL, ZSH, and Pyenv.

Additional resources for advanced configurations

If you’re interested in taking your setup further, here are some areas you can explore:

Custom ZSH Prompts: Personalize your terminal by creating custom ZSH prompts or using advanced themes like powerlevel10k.
ZSH Plugins: Explore more ZSH plugins to enhance your workflow. Some useful ones include zsh-autosuggestions, zsh-syntax-highlighting, and fzf.
Python Virtual Environments: Combine Pyenv with tools like pyenv-virtualenv to create and manage isolated Python environments for different projects.

Encouragement to personalize and experiment

Now that your development environment is set up, feel free to personalize it further! Experiment with different themes, plugins, and configurations to suit your workflow. The power of WSL and ZSH lies in their flexibility, so don’t hesitate to explore.

Good luck, and happy coding!!!

WSL Setup ( Ubuntu + ZSH + Pyenv)

Table of contents