How do I run doctests with PyCharm?

If you don't want to delete configurations, you can also hit the shortcut key for Run | Resume Program (F9 for me) to pop up a complete list of choices


Running a module (or the tests in it) in PyCharm is done via a Run Configuration. When you right click a module, PyCharm searches for an existing Run Configuration for that module. If a configuration is found (this can be due to a previous run, or a manual creation of a Configuration), PyCharm will only suggest to run that configuration.

For example, if a configuration of module.py was created to run its doctests, that is the option we'll see when right-clicking module.py. However, if no configuration is found, PyCharm suggests to run the module in different options, depending on the code in the module (run regularly, or run doctests / unittests). Once an option is chosen, PyCharm creates the respective, temporary, Run Configuration, implicitly. From here on, when right clicking the module, you'll only get the configuration that was created for that module.

Important side note: PyCharm saves up to 6 temporary (i.e., Configurations that were created via running a module) Run Configurations- 3 in "Python", i.e., scripts, and 3 in "Python Tests". This means that if you run moduleA.py, moduleB.py, moduleC.py, and then moduleD.py, the temporary Configurations in PyCharm will be moduleB.py, moduleC.py, and moduleD.py. The configuration of moduleA.py will be automatically deleted, unless explicitly saved.

This behaviour can be reproduced as following:

  1. In PyCharm, create a new Python module: "temp"

2.Add the following to the module:

"""
    >>> print 3.14
    3.14
"""

if __name__ == '__main__':
    pass
  1. Right click on the doctest section gives the option to "Run 'Doctests in temp' "
  2. Right click on the main section gives the option to "Run 'temp' "
  3. Choosing anyone of the options, makes the other option disappear in subsequent runs. E.g., choosing to run the module will make the option to run Doctests disappear in subsequent runs, and vice versa. Going back to the first stage, where it was possible to choose between the two options, is possible by deleting the module's "Run configuration":

Run --> Edit configuration --> Locate the module's current configuration (usually highlighted) --> Click the "Minus" button (top left corner) --> Click "Apply" --> Click OK. Now we are back at step 3.

(Reproduced in PyCharm 5.0 and 4.5)

To summarize:

  • If no Run Configuration is found, PyCharm suggests to run the module in any possible way (as a script, doctests, or unittests)
  • If a Run Configuration is found, PyCharm only suggests that Configuration.
  • If PyCharm isn't giving you the run option that you want, find the Run Configuration that is preventing it from giving you that option and delete it, or create a new one that will run the file, or method/function, the way you want.