How to Deploy an Ansible Development Environment from Scratch

Getting started with Ansible sounds easy—until your local environment starts fighting you. Version mismatches, Python conflicts, and missing dependencies can turn a simple automation task into a debugging session.

Let’s walk through a clean, repeatable way to deploy an Ansible development environment that won’t break the next time you install a package.

Why a Dedicated Ansible Dev Environment Matters

A common mistake developers make is installing Ansible globally and calling it a day. It works… until it doesn’t.

Here’s what typically goes wrong:

• System Python conflicts with Ansible dependencies
• Different projects require different Ansible versions
• Upgrades break existing playbooks

A proper Ansible development environment isolates everything so your automation stays predictable.

Step 1: Install Python and Verify Version

Ansible runs on Python, so this is your foundation.

Check your version:

1python3 --version

Ideally, use Python 3.9 or newer. If your system version is outdated, install a newer one via your package manager or tools like pyenv.

Step 2: Create a Virtual Environment

This is where things get clean. A virtual environment keeps Ansible isolated from your system.

1python3 -m venv ansible-dev
2cd ansible-dev
3source bin/activate

Once activated, your shell is now scoped to this environment.

Step 3: Install Ansible

With your virtual environment active:

pip install --upgrade pip
pip install ansible

Verify installation:

1ansible --version

You should see version details along with the Python interpreter path pointing to your virtual environment.

Step 4: Set Up a Project Structure

Instead of dumping playbooks into random folders, create a structure that scales.

1ansible-project/
2├── inventory/
3│   └── hosts.yml
4├── playbooks/
5│   └── site.yml
6├── roles/
7├── group_vars/
8├── host_vars/
9└── ansible.cfg

This layout keeps your configuration, variables, and roles organized as your automation grows.

Example Inventory File

1all:
2  hosts:
3    webserver:
4      ansible_host: 192.168.1.10
5      ansible_user: ubuntu

Step 5: Configure ansible.cfg

Here’s where you customize behavior. Create an ansible.cfg file in your project root:

1[defaults]
2inventory = ./inventory/hosts.yml
3host_key_checking = False
4retry_files_enabled = False
5

This avoids SSH prompts and unnecessary retry files during development.

Step 6: Test with a Simple Playbook

Before building complex roles, verify everything works with a minimal playbook.

1- name: Test connectivity
2  hosts: all
3  gather_facts: no
4  tasks:
5    - name: Ping hosts
6      ansible.builtin.ping:

Run it:

1ansible-playbook playbooks/site.yml

If everything is configured correctly, you’ll get a successful ping response.

Adding Developer Tooling

This is where your environment becomes truly productive.

Install Ansible Lint

$ pip install ansible-lint

Run it against your project:

1ansible-lint

It catches common mistakes early—missing handlers, improper module usage, and more.

Use Pre-commit Hooks

Automate checks before code is committed.

$ pip install pre-commit

Create a .pre-commit-config.yaml:

1repos:
2  - repo: https://github.com/ansible/ansible-lint
3    rev: v6.0.0
4    hooks:
5      - id: ansible-lint

Then enable it:

1pre-commit install

Working with Collections

Ansible collections package modules, roles, and plugins.

Install a collection:

1ansible-galaxy collection install community.general

Pin versions in a requirements file:

1collections:
2  - name: community.general
3    version: ">=6.0.0"

Common Pitfalls (and How to Avoid Them)

• Using system Python: Always stick to virtual environments
• Hardcoding IPs: Use inventory variables instead
• Skipping linting: Errors compound quickly in automation
• Ignoring version control: Track playbooks and configs in Git

Performance Tips for Local Development

Even in a dev environment, speed matters.

• Disable fact gathering when not needed (gather_facts: no)
• Limit execution scope using --limit
• Use tags to run specific tasks

Where This Setup Shines

This approach works especially well when:

• You manage multiple Ansible projects
• You need reproducible environments across teams
• You want safe experimentation without breaking production configs

Wrapping Up

A well-structured Ansible development environment removes friction and lets you focus on automation instead of debugging your setup. The combination of Python virtual environments, clean project structure, and tooling like ansible-lint creates a workflow that scales from simple scripts to complex infrastructure orchestration.

Once this foundation is in place, adding roles, integrating CI/CD, or connecting to cloud providers becomes significantly smoother.