Getting Started with Ansible Development on Windows Using WSL and Visual Studio Code

Windows Subsystem for Linux (WSL) is a compatibility layer that allows you to run a Linux environment directly on Windows, without the need for a virtual machine or dual-boot setup. It provides native access to a full Linux command-line experience, enabling developers to use Linux-based tools like Ansible, Git, and Python seamlessly alongside their Windows workflows. WSL is especially beneficial for Ansible development, as it provides a native-like environment for testing and executing playbooks, while still leveraging the convenience of the Windows desktop.

Visual Studio Code (VS Code) is a lightweight, open-source code editor developed by Microsoft. It supports a wide range of programming languages and comes with powerful features such as IntelliSense, debugging, Git integration, and an extensive marketplace of extensions. For Ansible development, VS Code offers extensions for YAML syntax highlighting, linting, and integration with WSL, making it an ideal environment for writing, testing, and managing playbooks.

The combination of WSL and Visual Studio Code provides a powerful and streamlined environment for developing and testing Ansible playbooks, all without the need to switch between different systems. It brings the best of both worlds: the flexibility of a Linux-based CLI and the productivity of a modern Windows-based editor.

The following benefits can be achieved:

• Full Intellisense for Ansible code.
• Syntax highlighting.
• Linting to ensure code consistency.
• YAML syntax validation.
• Full access to Ansible CLI tools and easily run playbooks, test roles, and use ansible-galaxy to create, install, or manage collections.
• VS Code Remote – WSL integration allowing you to edit and execute Ansible content inside WSL while using the full power of the VS Code interface, including integrated terminal, Git tools, and debugging.
• Access to Python virtual environments to easily isolate Ansible and dependency versions using venv or pip.

Installing Windows Subsystem for Linux (WSL)

This section assumes that you have the WSL command line available, but if you are not running Windows 11 or using an older version of Windows 10, then check the Microsoft page on Manual installation steps for older versions of WSL.

Open a command prompt and run the wsl command. You should see output similar to the following:

>wsl
Windows Subsystem for Linux has no installed distributions.
You can resolve this by installing a distribution with the instructions below:

Use 'wsl.exe --list --online' to list available distributions
and 'wsl.exe --install <Distro>' to install.

The command wsl --list --online will display a list of available Linux distributions that can be installed. At the time of writing, the following are available:

>wsl --list --online
The following is a list of valid distributions that can be installed.
Install using 'wsl.exe --install <Distro>'.

NAME                            FRIENDLY NAME
AlmaLinux-8                     AlmaLinux OS 8
AlmaLinux-9                     AlmaLinux OS 9
AlmaLinux-Kitten-10             AlmaLinux OS Kitten 10
AlmaLinux-10                    AlmaLinux OS 10
Debian                          Debian GNU/Linux
FedoraLinux-42                  Fedora Linux 42
SUSE-Linux-Enterprise-15-SP6    SUSE Linux Enterprise 15 SP6
SUSE-Linux-Enterprise-15-SP7    SUSE Linux Enterprise 15 SP7
Ubuntu                          Ubuntu
Ubuntu-24.04                    Ubuntu 24.04 LTS
archlinux                       Arch Linux
kali-linux                      Kali Linux Rolling
openSUSE-Tumbleweed             openSUSE Tumbleweed
openSUSE-Leap-15.6              openSUSE Leap 15.6
Ubuntu-18.04                    Ubuntu 18.04 LTS
Ubuntu-20.04                    Ubuntu 20.04 LTS
Ubuntu-22.04                    Ubuntu 22.04 LTS
OracleLinux_7_9                 Oracle Linux 7.9
OracleLinux_8_10                Oracle Linux 8.10
OracleLinux_9_5                 Oracle Linux 9.5

My personal preference is AlmaLinux, as it delivers a stable and reliable Red Hat Enterprise Linux experience, very much like using CentOS in the past. It’s a great choice for anyone looking for RHEL compatibility, and I highly recommend it for development and automation workloads.

That said, Ubuntu is also a great alternative, especially if you’re more familiar with its ecosystem. Both distributions provide access to modern toolchains and come with Python 3.10 or later, making them ideal for Ansible development. It’s also possible to install both at the same time.

The following will be based on AlmaLinux. Run the following command to install AlmaLinux-10 (or the latest version available):

wsl --install --AlmaLinux-10

WSL will proceed to download and install the selected distribution. Set your username and password when prompted.

>wsl --install AlmaLinux-10
Downloading: AlmaLinux OS 10
Installing: AlmaLinux OS 10
Distribution successfully installed. It can be launched via 'wsl.exe -d AlmaLinux-10'
Launching AlmaLinux-10...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: stephensg
New password:

I recommend updating the system as the first task.

sudo dnf update -y

Next, install the git client and Python pip.

sudo dnf install git python3-pip -y

Create Environment for Ansible Development

The next step is to create a Python virtual environment dedicated to Ansible development. This environment will isolate all required packages, ensuring a clean and controlled setup. Once the environment is configured, we’ll connect it to Visual Studio Code so that your Ansible tools and dependencies are available directly within the editor.

When you enter WSL for the first time, the current working directory will be your Windows user profile. I recommend switching to the Linux home directory to avoid annoying permission issues.

cd ~

Next, create a folder that will be used for the virtual environments (I use venv, but choose what suits you best)

mkdir venv

Create a new Python virtual environment used for Ansible development.

python -m venv venv/ansible-dev

This will result in a new directory being created under venv.

Activate the virtual environment:

source venv/ansible-dev/bin/activate

The prompt will change and display the virtual environment in parentheses:

[stephensg@Mandark ~]$ source venv/ansible-dev/bin/activate
(ansible-dev) [stephensg@Mandark ~]$

It’s also a good idea to ensure that pip is updated to the latest version before installing any packages. This helps avoid compatibility issues and ensures access to the most recent features and improvements. You can update it with the following command:

pip install --upgrade pip

Now that we’re inside the ansible-dev virtual environment, we can install the necessary packages for Ansible development. Thankfully, this process has been greatly simplified with the ansible-dev-tools package, which bundles everything you need for developing across all aspects of Ansible, including playbooks, roles, collections, and plugins.

Install the ansible-dev-tools package as follows:

pip install ansible-dev-tools

Once the installation is complete, you’ll notice that a variety of Ansible-related commands are now available.

(ansible-dev) [stephensg@Mandark ~]$ ansible
ansible            ansible-console    ansible-galaxy     ansible-navigator  ansible-runner     ansible-vault
ansible-builder    ansible-creator    ansible-inventory  ansible-playbook   ansible-sign
ansible-config     ansible-doc        ansible-lint       ansible-pull       ansible-test

Visual Studio Code Setup

This section assumes that Visual Studio Code is already installed. If it’s not, you can download it from the official website before continuing.

Next, you’ll need to install a few extensions. I recommend creating a dedicated profile in Visual Studio Code first. This lets you manage multiple profiles with different sets of extensions, making it easy to switch contexts based on the development environment you’re working in.

Click on the cog icon in the bottom left corner and select Profiles.

Click the New Profile button at the top.

Give this profile a name (I simply called it Ansible) and click Create.

When extensions are installed, they will be in the context of this profile.

Click on the Extensions button in the left panel and search for WSL.

Click Install to install the extension. Once installed, press F1 or CTRL+SHIFT+P to bring up the command palette and type WSL. Select WSL: Connect to WSL.

This will refresh the VS Code window and install the required server components on the WSL instance.

Install the Ansible extension from the marketplace. This extension will be installed on the WSL instance along with any other dependencies (such as Python, YAML, etc).

Create and Configure VS Code Workspace

At this stage, I recommend saving the project as a Workspace. This will allow a single workspace (including settings) to be used for all types of Ansible development (playbooks, roles, plugins).

Select File -> Save Workspace As and give the workspace an appropriate name (I used ansible.code-workspace for my example).

Now we need to add some configuration to the workspace to ensure the Ansible extensions function correctly, including support for tools like Ansible Lint. Press CTRL+SHIFT+P and search for Workspace Settings. Select the option which includes JSON.

Add the following settings in the settings {} block, using the full path to your virtual environment (I found that ~ does not work well here).

"ansible.python.interpreterPath": "/home/stephensg/venv/ansible-dev/bin/python",
"ansible.validation.lint.enabled": true,
"ansible.validation.lint.path": "/home/stephensg//venv/ansible-dev/bin/ansible-lint",
"ansible.validation.lint.arguments": "--parseable --offline",
"python.defaultInterpreterPath": "/home/stephensg/venv/ansible-dev/bin/python",
"python.terminal.activateEnvironment": true,
"python.terminal.activateEnvInCurrentTerminal": true,
"files.associations": {
    "*.yml": "ansible"
},

These settings ensure that the Ansible extension and ansible-lint correctly parse all .yml files, not just main.yml. Additionally, they automatically activate the virtual environment in the VS Code terminal, so you won’t need to do it manually each time you open the project.

Add projects to VS Code Workspace

Now that VS Code is fully configured, it’s time to add your Ansible projects to the workspace. On the WSL instance, you can add your existing Ansible projects (copy them directly or checkout from Git) or create a new empty project (using ansible-galaxy from the terminal)

For my example, I have added my existing project ansible-role-vmware-avi, which I have placed in a directory called ansible-projects in my home directory.

Within VS Code, select File -> Add Folder to Workspace... and browse to and select the Ansible project.

After clicking Add, the project will now be visible within the workspace on the left.

Exploring some of the benefits of using WSL and VS Code

The first thing to demonstrate is that upon opening VS Code or the project, the terminal immediately activates the virtual environment that I specified in the workspace settings.

I deliberately picked the project in the previous step, as it’s old and pre-dates the introduction of Ansible Collections, so I knew there would be a few issues flagged for demonstration. In the screenshot below, you can see a number of issues that have been flagged in my YML file (picked up by ansible-lint).

Also, a list of all issues found in this file is listed under Problems.

The screenshot below demonstrates the correction of a fully qualified collection name (FQCN) error, where IntelliSense is used to automatically suggest and apply the correct command.

You’ll also notice the syntax highlighting applied to the file, which greatly improves readability and makes it easier to identify errors at a glance.

This setup adds significant value to Ansible development and can be extended even further through additional extensions, Python linting integration, or by customising ansible-lint to suit your specific needs.

I hope you found this post helpful. If you’re using WSL for Ansible development and have any tips, tools, or cool workflows to share, feel free to drop a comment. I’d love to hear about it!