Debugging Custom Ansible Modules with PyCharm

Ansible is an easy configuration management system that can be used to automate and organize system configuration tasks for a large network of computers. With Ansible, you only need to install a server component, called the Ansible Control Machine, and this node only requires SSH access to the client machines, which means no agents are required to be installed on the client machines.

Ansible, comes out of the box with a plethora of modules available for system configuration tasks like creating user, installing packages and also with numerous module for cloud vendors like AWS, DigitalOcean, etc. Though, there are times where, writing a custom module for certain tasks becomes necessary, for internal requirements. While writing custom modules, one would need to be able to debug modules, which would ease module development.

In this post, I would like to provide insight in to a way of debugging modules, using Ansible’s test-module script and PyCharm IDE, on a Ubuntu 14.04 Vagrant Instance.


  • A Workstation, with Pycharm Professional Edition, can be any Operating System
  • Ubuntu 14.04 Vagrant Machine, which will be the Ansible Controller Machine or the debugging machine

Ubuntu 14.04 Vagrant Machine Setup:

The minimum Vagrant file configuration required for the setup to work is as below. Note the line, where the private network is configured, this makes it possible for the vagrant machine to connect to the workstation over the IP address for debugging purpose. Create a directory at any location of your choice on the workstation and place the below vagrant config as Vagrantfile.

Vagrant.configure("2") do |config| = "ubuntu/trusty64" "private_network", ip: ""
config.vm.provider "virtualbox" do |vb|
vb.memory = "1024"

Now in the same directory as the Vagrantfile do the following,

# Create a directory on the folder for keeping the custom modules # Windows user's please use git bash for the following
mkdir custom_modules
# Clone ansible from git
# As we need the hacking/test-module script for debugging
git clone git:// --recursive
cd ansible/
git submodule init && git submodule update

Now, the final project tree would look like,

├── ansible
│ ├── ansible-core-sitemap.xml
│ ├── bin
│ ├──
│ ├──
│ ├── contrib
│ ├──
│ ├── docs
│ ├── docs-api
│ ├── docsite
│ ├── examples
│ ├── hacking
│ ├── lib
│ ├── Makefile
│ ├──
│ ├── packaging
│ ├──
│ ├── RELEASES.txt
│ ├── ROADMAP.rst
│ ├──
│ ├── shippable.yml
│ ├── test
│ ├── ticket_stubs
│ ├── tox.ini
├── custom_modules
│ └──
└── Vagrantfile

The contents of the, which will be the custom module is as below


import json
except ImportError:
import simplejson as json

import os

module: OSCheckModule
short_description: A custom module to check OS of target machine.
- A custom module to check OS of target machine.
- Name of OS to check
required: true

# Example
os_name: Linux

def main():
module = AnsibleModule(

# Retreive parameters
os_name = module.params['os_name']

# Check for OS
if os_name in os.uname():
# Successfull Exit
module.exit_json(changed=True, msg="OS Match")
# Fail Exit
module.fail_json(msg="OS Mismatch. OS =" + os.uname()[0])

from ansible.module_utils.basic import AnsibleModule

if __name__ == '__main__':

Finally, It’s time to fire-up the Vagrant machine, and configure it for ansible

vagrant up && vagrant ssh
sudo apt-get install python-pip build-essential python-dev
sudo pip install ansible paramiko PyYAML Jinja2 httplib2 six markupsafe pydevd

Configuring PyCharm

  1. First, we have to configure the default python interpreter for our ansible project. Open the folder containing Vagrantfile with PyCharm.
  • Go to File -> Setting -> Project -> Project Interpreter.
  • In the window, click on the gear icon on the right (Please refer to the screenshot below)
  • In the pop-up that appears, select vagrant and select the default python interpreter. After the vagrant remote is configured, change the python interpreter to python 2.7. And finally your screenshot should be similar to the below screenshot

2 . Secondly, after configuring the default interpreter for the project, now the Run/Debug settings for the project has to be configured,

  • Go to Run ->Edit Configurations
  • On the screen that appears click the + button to the left-top corner and select Python Remote Debug and enter details as in the below screenshot
  • Note: The IP address may vary if you are using a different IP address in the Vagrantfile
  • Give a name for the configuration, enter Localhost name as and the port as 54655 and click Apply and Save.

Debugging Ansible

Now click the Debug icon on the top-right corner and you will get the Debug console at the bottom of the screen like below, with the required details

  • Add the the line “import pydevd” to the top of the file, for importing the pydevd module
  • In order to set the breakpoint in the file, add the below line, in the place where the breakpoint is to be set
pydevd.settrace(‘’, port=54655, stdoutToServer=True, stderrToServer=True)
  • Login to the vagrant machine via ssh and execute the below command
  • Note: Make sure that the vagrant machine is able to ping the IP and use netcat to check if the port is reachable too.
/vagrant/ansible/hacking/test-module -m /vagrant/custom_modules/ -a os_name=Linux
  • Now, PyCharm should prompt with a screen like the following
  • Click on Download, optionally you can check the Remember for Debug session checkbox, and then you should see the module with the break point set as in the below screenshot.
  • After the Debugging session you should be able to see the output in the console tab of the debugging view
Happy Debugging !!!

Please do, throw in your questions, if you have any trouble setting this up.

I would like to thank Mumshad Mannambeth, for his github document which helped me in setting this up, and my Team for their support and encouragement.