This project is being split into 3 separate projects:

  • friendly_traceback,

  • friendly, and

  • friendly_idle.

The documentation does not reflect this change.

If you are a end-user, just install friendly until further notice.

Basic usage

There are various ways of using friendly. I only list here the basic scenarios available from a terminal or from within a Python interpreter. More options are possible, including running from an editor/IDE as described later in this documentation.

For those that know how to run programs from a terminal, I recommend using one of the first three following options.

  1. Execute a Python program, as I have already shown at the beginning:

    $ python -m friendly example.py
  2. You can also start a friendly console:

    $ python -m friendly
  3. Combining the two options above by using Python’s -i flag to start friendly’s console after executing a program:

    $ python -im friendly example.py

All of the above assume that you are using a terminal with a dark background. If you are using a terminal with a light background, you might want to add --style light as a command line option.

More ways to use

The following ways of using friendly are described in more details later. I simply list them here as useful summary for experienced Python programmers.

  1. You can use friendly as an exception hook:

    import friendly
    friendly.install()  # replaces the default sys.excepthook
  2. Starting the console from any Python interpreter:

    >>> import friendly
    >>> friendly.start_console()
  3. You can also use it to catch exceptions locally:

    import friendly
        # Some code
    except Exception:

All of the above support additional options allowing one to select a different language (only French for now) or changing the information that is shown by default.

More information about various additional options is provided later in this documentation. As a shortcut, you can also type python -m friendly -h in a terminal.


You can use friendly with the logging module. Here’s an example, together with the corresponding output:

import friendly
import logging

# Configure as desired before running the code
friendly.set_lang('fr')  # Just as an example :-)

    import ignore2
except Exception:
    # Note: friendly often remove some details from tracebacks
    # to make them more readable. This can be helpful
    # but sometimes we might also need to see the full
    # traceback in log files.
    # For example, compare the path of ignore2.py shown
    # in both tracebacks.
    log = (" Friendly traceback\n" +
              friendly.get_output() +
              "\n----Original traceback-----\n")
    # exc_info=True below will append the original traceback
    logging.error(log, exc_info=True)

And here’s the output:

ERROR:root: Friendly traceback

Traceback (most recent call last):
  File "ignore.py", line 9, in <module>
    import ignore2
  File "CWD:\ignore2.py", line 3, in <module>
    c = a / b
ZeroDivisionError: division by zero

    Une exception de type `ZeroDivisionError` se produit lorsque vous essayez de diviser une valeur
    par zéro soit directement ou en utilisant une autre opération mathématique.

    Vous divisez par le terme suivant


    qui est égal à zéro.

    L'exécution s'est arrêtée à la ligne 9 du fichier ignore.py

        8: try:
    --> 9:     import ignore2
       10: except Exception:

    Exception levée à la ligne 3 du fichier CWD:\ignore2.py.

       1: a = 1
       2: b = 0
    -->3: c = a / b

            a:  1
            b:  0

----Original traceback-----
Traceback (most recent call last):
  File "ignore.py", line 9, in <module>
    import ignore2
  File "C:\Users\andre\github\friendly\ignore2.py", line 3, in <module>
    c = a / b
ZeroDivisionError: division by zero