Installing WSL2 & Ubuntu

This page explains how to install the Windows Subsystem for Linux (WSL2) with Ubuntu in preparation for installing DDEV & Drupal.

It also offers some basic guidance for newcomers to Linux/Ubuntu, and shows how to configure your environment via Microsoft Terminal, Zsh, command aliases etc. to make it more pleasurable to use.

Refer to these Microsoft guides for more information on WSL:

• How to install Linux on Windows with WSL
• Troubleshooting Windows Subsystem for Linux
• Manual installation steps for older versions of WSL

Before proceeding, make sure you understand the process and that your PC is ready by reading the previous page: Overview, System Requirements & Virtualization.

Search "PowerShell" in the Windows search.

Run wsl --install (as this is a global activity, the directory from which you run this command from doesn't matter). There is usually no need to specify a Linux distribution as an option to this command; the default version of Ubuntu installed should be a good choice. The following will be installed:

• The Virtual Machine Platform
• Windows Subsystem for Linux (WSL2)
• Host Process for Windows Services 

Click "Yes" if asked if you want to allow these applications to make changes to your device.

On most systems you will now be required to reboot. 

After booting up, you'll normally have to do `wsl --install` again. After Ubuntu completes installing itself, enter your username at the Enter new UNIX username: prompt. Your home directory will be given this name in the format /home/myname. A short, all-lower case name may be preferable. Enter your password at the New password: prompt. You will be asked for this password very often while using Ubuntu, so don't make it too long. Nothing will be shown as you type it.

At the $ prompt, verify that you have an Ubuntu distribution set as default by running wsl.exe -l -v. You should see output like this:

  NAME      STATE           VERSION
* Ubuntu    Running         2

If not, troubleshoot using the Microsoft guides linked above.

The Ubuntu terminal has been installed as this Windows app. There is no need to install it again. New terminals opened with the app will have the newer, orange Ubuntu logo at the top left.

Keep WSL2 up to date

In Windows Update → Advanced options → Update options, enable Receive updates for other Microsoft products when you update Windows.

Run wsl -v in a Powershell to compare the installed version with the WSL Releases. Update with wsl.exe --update.

If you want to push on and get DDEV installed, you can now jump to that page. If you are new to Ubuntu or Linux, then the rest of this page offers some basic guidance on using Ubuntu and shows how you can configure your environment to make it more pleasurable to use via Microsoft Terminal, Zsh, command aliases etc..

Administrative privileges

In Ubuntu, the root ("superuser") account is disabled for security reasons and to prevent you making mistakes. By default your user account is prevented from running commands that affect the file system above your home directory. However, because you were the one who installed Ubuntu, your user account is part of the sudo group, so you can temporarily "become" superuser, to run commands with root privileges, by preceding the command with sudo .

Ubuntu commands

You now have Ubuntu running inside Windows, and you need a few command line skills to survive. The commands are different to Windows commands, so at this stage, if you are unfamiliar with Linux, you may wish to follow The Linux command line for beginners guide. Here are some commands to get you started:

• pwd Print working directory (i.e. show me which folder I am in).
• ~ Go to my home directory (/home/myname).
• cd /path/folder1 Change directory to /path/folder1. You can omit the cd, but be careful the final part of the path is not a Linux command!
• . This directory.
• .. The parent directory.
• ls List contents of the current directory.
• ls -la List contents of the current directory in long format, including hidden files.
• find ~ -name file1 Search for files called file1 below my home directory.
• sudo someCommand Run someCommand with superuser privileges. Required for many operations.
• mkdir folder1 Make directory called folder1.
• touch file1 Make an empty file called file1.
• cp file1 file2 Copy file1 to file2.
• cp file1 folder2 Copy file1 to folder2.
• mv file1 folder2 Move file1 to folder2.
• mv file1 file2 Rename file1 to 'file2'.
• rm file1 Remove (delete) file1.
• rm -r folder1 Remove folder1 and its contents.
• cat file1 View the contents of file1 in your terminal. There are other ways.
• chmod +x file1 Add executable permissions for a file.
• Up Arrow (& down arrow) - Scroll through previously-issued commands, to re-use or edit and reuse one.
• ^foo^bar Replace foo with bar in the last command and run it.
• CTRL + U Clear the current line.
• clear Clear the terminal window.
• man someCommand Show the manual page for someCommand.
• history Show a list of previously executed commands in the current terminal session.

If you need to get back to an prompt in Ubuntu, CTRL+C or Q usually work, depending what you are doing. ESC generally does not work.

Ctrl+R initiates a reverse search of your command history, allowing you to find and re-run previous commands by typing a portion of the command. 

The Windows path to Ubuntu

The Windows path of your home directory in Ubuntu is \\wsl.localhost\Ubuntu\home\myname. Add it where you can easily open it later (e.g. the Quick Access list in Windows File Explorer).

Ubuntu GUI apps vs Windows GUI apps

You may wish to try some native Linux utility apps, although you don't really need to. On all supported Windows versions it is possible to run Linux GUI applications on WSL2 without installing a 3rd-party X11 server such as VcXsrv.

From the GNOME apps, simple apps such as the file manager, Files (also known as Nautilus) and Text Editor should run OK. More complex Linux applications under WSL2 can be "clunky", their GUIs may suffer rendering glitches (depending on your GPU and driver), and they may be difficult to install (e.g. Krusader and Kate).

Most people prefer to use native Windows GUI applications.

If you need to use a file manager for the files within your Ubuntu file system, you can just use your Windows file manager. But note that, when logged in as a regular (non-root) user, you cannot use graphical file managers for file operations that affect files above your Ubuntu home directory. In such cases you would have to use the command line (e.g. sudo mv file1 /usr/local/share) and enter your password when asked.

You don't need to install a native Linux browser. DDEV in WSL2 will open Windows browsers.

The Linux version of DBeaver runs, but is probably not your best choice of database manager in a DDEV/WSL2 scenario.

Windows Terminal (recommended)

Windows Terminal ships with Windows and is an excellent way to access your Ubuntu distro. It allows you to run an Ubuntu shell and a Microsoft Powershell etc. in tabs or panes in the same window, and adds other support such as Unicode and UTF-8. Choose different shells from the drop-down menu at the top.

After installing, open it, drag it wide enough to see the full titles in the left panel, and open the settings using the prompt at the top, or from the drop-down menu. If you see an "Ubuntu" profile with a Linux penguin logo, as well as an Ubuntu profile with an orange Ubuntu logo, open the "penguin" one, scroll to the bottom, and click "Delete profile" delete it.

There are a lot of settings to customize it. Here are some settings you might change from their defaults:

• Startup 
  • Default profile: Ubuntu
  • Launch size: Columns: 85, Rows 32
  • Launch parameters: Default, X: 0, Y: 0  (so Windows Terminal always opens at the top left of your display)
• Appearance
  • Hide the title bar: Off
  • Always show tabs: On
• Color schemes
  • The colors in the Ubuntu-ColorScheme can be difficult to see. So you could make a custom scheme for Ubuntu, for example like Campbell but with dark purple background so you instantly see that you are in an Ubuntu tab.
• Profiles → Ubuntu
  • Command line: Important - Change ubuntu.exe to wsl.exe -d Ubuntu, so the following line works (explanation).
  • Starting directory: //wsl.localhost/Ubuntu/home/myname/sites  (your DDEV projects folder. Uncheck Use parent process directory so you can enter the path.)
  • Additional settings → Appearance → Cursor: Bar ( | )

Put a shortcut to the Windows Terminal where you access frequently-used apps. e.g. The Windows Quick Launch bar.

Zsh (optional)

Let's make your Ubuntu terminal more pleasant to use. Z Shell (Zsh) is a shell that has improvements over Ubuntu's default Bourne shell (bash), such as improved path expansion, advanced auto-completion, and interactive command history. It is the default shell for MacOS. Install by running:

sudo apt install zsh

Oh My Zsh

Zsh shines when you add functionality via plugins and a theme. They can greatly improve the command line experience, especially for a newcomer coming from Windows. But unfortunately Zsh plugins can be complicated to install and keep up-to-date manually.

Oh My Zsh is a popular framework to make Zsh plugin management easier. It is widely used, well documented, and provides many of its own plugins that can be difficult to install in other ways. There are several more lightweight Zsh plugin managers, but they tend to be problematic, poorly maintained and short-lived.

Install Oh My Zsh by using the following command, then accept the prompts to set Zsh as your default shell.

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

Zsh configuration is in your ~/.zshrc file. During the following steps, to reload the config without closing and reopening your terminal, run source ~/.zshrc. If that doesn't work, try exec Zsh.

Zsh plugins

Bundled plugins are in ~/.oh-my-zsh/plugins. Put your custom plugins in ~/.oh-my-zsh/custom/plugins.

Enable a plugin by adding its name to the plugins array in your .zshrc file. You may find you have the git plugin by default. Here's an entry which also enables some other very useful plugins, that don't require much installation:

plugins=(git zsh-autosuggestions zsh-syntax-highlighting dirhistory sudo)

• git - Many Git aliases and a few useful functions. Git is installed by default with Ubuntu.
• zsh-autosuggestions - Suggests commands as you type based on history and completions. You'll also need to clone the repository by running git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions.
• zsh-syntax-highlighting - Syntax highlighting as you type. You'll also need to clone the repository by running git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting. The colors can be tweaked with a line such as ZSH_HIGHLIGHT_STYLES[arg0]='fg=#00ff00' in your .zshrc file. Refer to ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting/highlighters/main for the default style names.
• dirhistory - Press Alt + Left to scroll through past directories you were in, and Alt + Right to return to more recent directories.
• sudo - Prefix your current or previous command by pressing ESC twice. Saves you retyping the whole command when Ubuntu refuses permission to run it.

See Top Popular ZSH Plugins on GitHub and awesome-zsh-plugins for more Zsh plugins. Some are a little complex to set up. Don't install too many!

Zsh themes

Via Oh My Zsh you can choose a custom Zsh theme. Set your default theme and other preferences in ~/.zshrc. Bundled themes are in ~/.oh-my-zsh/themes. 

You can create your own theme to customize the colors etc. and display of the user, path, time, and Git branch etc.. Put custom themes in ~/.oh-my-zsh/custom/themes.  This simple example theme shows the full path, the Git branch (with dirty/clean info), and a green $ after a successful command or a red $ after a failed command:

PROMPT="%F{#0ff}%~%{$reset_color%}"
PROMPT+=' $(git_prompt_info)'
PROMPT+="%(?:%F{#2e2}%1{$%}:%F{red}%1{$%})%{$reset_color%} "

ZSH_THEME_GIT_PROMPT_PREFIX="%{$reset_color%}%F{#f60}"
ZSH_THEME_GIT_PROMPT_SUFFIX="%{$reset_color%} "
ZSH_THEME_GIT_PROMPT_DIRTY=" %F{#fc0}*%{$reset_color%}"
ZSH_THEME_GIT_PROMPT_CLEAN=""

The advanced theme, powerlevel10k, is popular, but requires additional installation.

Command aliases

Set up command line aliases to save typing in your Ubuntu terminal by adding lines such as those below to your ~/.zshrc file. You would then, for example, be able to run ddev composer update by just entering cup. After adding aliases, run source ~/.zshrc to re-read the config.

Before setting an alias, check it doesn't already exist as a command or alias by running type commandName. List existing aliases by entering alias.

Note that the Zsh git plugin, installed by default with Oh My Zsh, adds a huge number of Git aliases (code).

alias cl="clear"
alias fn="find -name"
alias open="wslview"

# PROJECT NAMES
alias blog="cd ~/sites/cat-blog"
alias shop="cd ~/sites/my-shop"

# DDEV
alias st="ddev start"
alias rst="ddev restart"
alias go="ddev launch"
alias stop="ddev stop"
alias off="ddev poweroff"
alias bs="ddev browsersync"
alias ad="ddev adminer"
alias list="ddev list"
alias ll="ls -la"
alias my="ddev mysql -A"
alias wb="ddev wb" #MySQLWorkbench
alias cup="ddev composer update"
alias xon="ddev xdebug"
alias xoff="ddev xdebug off"
alias exp="ddev export-db -f"
alias sn="ddev snapshot -a" #Cannot use ss

# DRUSH
alias updb="ddev drush updb"
alias cex="ddev drush cex" #Config export
alias cr="ddev xdebug off && ddev drush cr"

# GIT
alias gac="git add -A && git commit -m"

Next steps

With WSL2 and Ubuntu installed and configured, you are now ready to install Docker, DDEV & Drupal.