Debugging Custom Ansible Modules with PyCharm


  • 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"
# 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
├── 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

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__':

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
  • 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
  • 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.
  • 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.



Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store