Ansible is a powerful tool for automating IT tasks, from server management to cloud provisioning. If you're using Visual Studio Code (VS Code) for your development, you can integrate Ansible to streamline your workflow.

In this guide, I'll show you how to set up Ansible within VS Code, enabling you to write, test and run your automation scripts with ease.

Why Use Ansible with VS Code?

VS Code is a popular, lightweight code editor that offers extensive features through its marketplace of extensions.

By integrating Ansible with VS Code, you gain:

  • Syntax highlighting and linting for Ansible playbooks.
  • Autocompletion for Ansible modules and parameters.
  • A convenient development environment for writing and testing automation scripts.
  • Integration with Python virtual environments and Docker containers.

Step 1: Install Visual Studio Code

If you haven't already, download and install Visual Studio Code on your machine.

VS Code is available for macOS, Windows and Linux.

Download it from the official website:

https://code.visualstudio.com/

Note: Ansible can run directly on Linux and macOS. Windows users should use Windows Subsystem for Linux (WSL), as Ansible does not support native Windows as a control node.

Step 2: Install the Required Extensions

To work effectively with Ansible in VS Code, you'll need a few extensions.

2.1 Python Extension

The Python extension is useful when working with Python-based Ansible modules, filters and development environments.

To install it:

  1. Open VS Code.
  2. Navigate to the Extensions view:
    • Windows/Linux: Ctrl + Shift + X
    • macOS: Cmd + Shift + X
  3. Search for Python.
  4. Install the official Python extension by Microsoft.

2.2 Ansible Extension

For Ansible-specific functionality:

  1. Open the Extensions view.
  2. Search for Ansible.
  3. Install the Ansible extension by Red Hat.

The extension provides features including:

  • Syntax highlighting for Ansible YAML files.
  • Autocompletion for modules and parameters.
  • Playbook validation.
  • Integration with Ansible linting tools.

Note: Some features require additional dependencies, such as ansible-lint, and an appropriate Ansible execution environment.

Step 3: Set Up a Python Virtual Environment

Using a Python virtual environment helps isolate project dependencies and avoid conflicts with system-wide Python packages.

3.1 Install Python Prerequisites

Before creating a virtual environment, ensure Python and the required tools are installed.

On Ubuntu/Debian:

sudo apt update sudo apt install -y python3 python3-pip python3-venv

For macOS, ensure Python 3 is installed and available in your terminal.

Windows users should perform the following Ansible installation steps inside a WSL Linux environment.

Verify that Python is available:

python3 --version

3.2 Open the Integrated Terminal

Open the integrated terminal in VS Code using:

  • Windows/Linux: Ctrl + `
  • macOS: Ctrl + `

Alternatively, select Terminal > New Terminal.

Navigate to your project directory.

3.3 Create a Virtual Environment

Run the following command:

python3 -m venv .venv

This creates a virtual environment named .venv inside your project directory.

3.4 Activate the Virtual Environment

On Linux/macOS:

source .venv/bin/activate

On Windows using WSL:

Run the Linux activation command inside your WSL terminal:

source .venv/bin/activate

For general Python development in native Windows PowerShell, activation would use:

.\.venv\Scripts\Activate.ps1

However, Ansible itself should be installed and executed inside WSL rather than native Windows.

After activating the environment, your terminal will typically display (.venv) at the beginning of the prompt.

3.5 Install Ansible

With the virtual environment activated, install Ansible:

python -m pip install ansible

Verify the installation:

ansible --version

If Ansible is installed correctly, the command should display its version and configuration information.

3.6 Select the Python Interpreter in VS Code

To configure VS Code to use the virtual environment:

  1. Open the Command Palette:
    • Windows/Linux: Ctrl + Shift + P
    • macOS: Cmd + Shift + P
  2. Search for Python: Select Interpreter.
  3. Select the Python interpreter from your .venv virtual environment.

For Linux and macOS, the interpreter is typically located at:

.venv/bin/python

3.7 Configure the Ansible Extension

Selecting the Python interpreter for the Python extension does not necessarily configure the Red Hat Ansible extension to use the same environment.

If the Ansible extension cannot locate Ansible or its dependencies:

  1. Open VS Code Settings.
  2. Search for Ansible: Python Interpreter Path.
  3. Configure it to use the Python executable from your virtual environment.

For Linux/macOS, the interpreter path will resemble:

/path/to/your/project/.venv/bin/python

Replace the example with the actual path to your virtual environment.

This helps ensure that the Ansible extension uses the intended Python environment.

Step 4: Writing and Testing Ansible Playbooks

Now that the environment is configured, let's create a simple playbook to verify that Ansible works correctly.

4.1 Create a New Ansible Playbook

  1. Open your project directory in VS Code.
  2. Create a new file named playbook.yml.
  3. Add the following YAML configuration: 
--- - name: Test Ansible setup hosts: localhost connection: local gather_facts: false tasks: - name: Display a test message ansible.builtin.debug: msg: "Ansible is working correctly!"

This playbook executes a simple task on your local machine.

The ansible.builtin.debug module displays a message without making any system changes.

4.2 Run the Ansible Playbook

Open the integrated terminal and ensure your virtual environment is activated.

Execute:

ansible-playbook -i localhost, playbook.yml

Why is there a comma after localhost?

The comma tells Ansible to interpret localhost, as an inline inventory containing one host, rather than as the name of an inventory file.

The playbook uses connection: local, so no SSH connection to a remote server is required.

If everything is configured correctly, you should see output similar to:

PLAY [Test Ansible setup] TASK [Display a test message] ok: [localhost] => { "msg": "Ansible is working correctly!" } PLAY RECAP localhost : ok=1 changed=0 unreachable=0 failed=0

This confirms that Ansible can execute the playbook successfully.

4.3 Check the Playbook Syntax

Before executing a playbook, you can check its syntax:

ansible-playbook -i localhost, playbook.yml --syntax-check

This checks the playbook's syntax without executing its tasks.

However, a successful syntax check does not guarantee that every task will run successfully.

4.4 Install and Run Ansible Lint

Ansible Lint helps identify potential issues and encourages consistent coding practices.

Install it using:

python -m pip install ansible-lint

Verify the installation:

ansible-lint --version

Run Ansible Lint against your playbook:

ansible-lint playbook.yml

The tool analyses your playbook and reports issues based on its configured rules.

Some recommendations may require changes to the playbook to follow Ansible best practices.

The Red Hat Ansible extension can also integrate with Ansible Lint to display diagnostics inside VS Code.

Step 5: Optional — Using Docker for Testing

Docker can provide an isolated environment for developing and testing Ansible automation.

This is particularly useful when you want to experiment with different dependencies or avoid installing additional tools directly on your host system.

5.1 Install Docker

Ensure Docker is installed and running on your machine.

Official installation instructions are available at:

https://docs.docker.com/get-docker/

Verify your installation:

docker --version

You can also verify that the Docker daemon is accessible:

docker info

5.2 Install the Dev Containers Extension

VS Code supports development inside containers using the Dev Containers extension.

To install it:

  1. Open VS Code.
  2. Navigate to the Extensions view.
  3. Search for Dev Containers.
  4. Install the extension by Microsoft.

5.3 Attach VS Code to a Running Container

If you already have a suitable running Docker container:

  1. Open the Command Palette.
  2. Search for Dev Containers: Attach to Running Container....
  3. Select the running container.
  4. VS Code will open a development environment connected to that container.

You can now use VS Code's integrated terminal to work inside the container.

Important: Attaching VS Code to a Docker container does not automatically install Ansible or configure an Ansible testing environment.

The container must have the required dependencies, including Python and Ansible, installed and configured.

It must also have suitable access to any managed hosts or resources needed for your tests.

5.4 Consider Using a Dedicated Development Container

For repeatable development environments, you can configure a dedicated Dev Container using a devcontainer.json file.

This allows you to define the container environment and the tools required by your project.

A properly configured development container can make it easier to maintain consistent Ansible development environments across different machines.

Docker is optional for this tutorial. The simple localhost playbook from Step 4 can be executed directly from your Python virtual environment.

Conclusion

Integrating Ansible with Visual Studio Code provides a convenient environment for developing and testing automation scripts.

With features such as syntax highlighting, autocompletion, linting and Docker integration, you can improve your workflow and identify potential issues before deploying your playbooks.

Using Python virtual environments helps organise dependencies and makes it easier to maintain separate Ansible projects.

Whether you're managing a few Linux servers or working with larger infrastructure environments, combining Ansible and VS Code can make automation development more efficient.

Happy automating!