How do you set up Pycharm to debug a Fabric fabfile on Windows?

The fab executable is nothing but a simple python script. For example, with Fabric 1.10.2 it is just this (although I skipped the shebang and encoding lines):

import re
import sys

from fabric.main import main

if __name__ == '__main__':
    sys.argv[0] = re.sub(r'(-script\.pyw|\.exe)?$', '', sys.argv[0])
    sys.exit(main())

ie: all it is really doing is calling fabric.main.main(). I'm not sure why it is subbing out the windows extensions in sys.argv[0], but it doesn't really matter.

If you want to debug a fabfile, either just set the fab.py file as the script to be debugged by your IDE, or make a little stub file that calls fabric's main() and debug that. You can then put breakpoints anywhere in your fabfile, (or anything your fabfile imports) as you would with any other python program.

Aside from this, the main part you need is to be able to pass arguments to the executed script so that they show up in sys.argv. How to do this depends on your IDE/debugger. Or, you could just jam them in yourself, something like this:

import sys
from fabric.main import main

sys.argv[1:] = ["task1",."task2"] #or whatever you would give fab.
main()

Using your IDE/debugger method is much better, of course.

Here is how I ended up setting this up in case this is useful for someone else. As with most things like this, once you know the magic settings, it was very easy. All these instructions are through PyCharm but several of them can be done in alternate ways. However, since this is about debugging in PyCharm, that’s what I’m using for the instructions. Also, I’m using Windows.

Install Fabric package to the project environment (using the Settings-->Project Interpreter package installation). This installs Fabric to the virtual environment’s site package folder as well as putting a fab.exe and fab-script.py file in the /Scripts folder. Find the location of the fab-scripts.py file and copy the path (something like this “C:\\Scripts\fab-script.py”)

Now, create a run configuration (Run --> Edit Configuration… --> Python) with this script file name. The Script parameters point to the fabfile.py and the command to execute/debug. The Script parameters are: -f fabfile dev:"MyBranch1" deploy This allows me to debug the “dev” task with a “MyBranch1” parameter then run the “deploy” task. Replace the dev:"MyBranch1" deploy with whatever your task name is. The Working directory points to your project folder which is also where the fabfile.py is located (at least with my configuration). My setup looks like this.

Open the fabfile.py and put a breakpoint where you would like to stop the debugger. In this case, since I’m debugging the deploy task, I put the breakpoint there.

Now to debug the fab run, set the active configuration to the one just made and click debug.

When the breakpoint is hit, you are off and debugging your fabric fabfile.py with PyCharm

When you are ready to run your debugged fabfile, open the Terminal and run the fab command with the parameters used in the debugging. Again, point the command prompt at the project (working) directory. (NOTE: The fab.exe in the Scripts folder needs to be executable from the command line – by having it in the environment variables path property)

I followed the instructions above in the screenshots. Please be aware that fab-script above should contain:

import fabric.main

if __name__ == '__main__':
    fabric.main.main()