import

Ansible allows unchecked imports of some libraries from specific directories, listed at the bottom of this section. Import all other Python libraries in a try/except ImportError block to support sanity tests such as validate-modules and to allow Ansible to give better error messages to the user. To import a library in a try/except ImportError block:

  1. In modules:

    # Instead of 'import another_library', do:

import traceback

try:
    import another_library
except ImportError:
    HAS_ANOTHER_LIBRARY = False
    ANOTHER_LIBRARY_IMPORT_ERROR = traceback.format_exc()
else:
    HAS_ANOTHER_LIBRARY = True


# Later in module code:

module = AnsibleModule(...)

if not HAS_ANOTHER_LIBRARY:
    # Needs: from ansible.module_utils.basic import missing_required_lib
    module.fail_json(
        msg=missing_required_lib('another_library'),
        exception=ANOTHER_LIBRARY_IMPORT_ERROR)

  2. In plugins:

    # Instead of 'import another_library', do:

from ansible.module_utils.six import raise_from

try:
    import another_library
except ImportError as imp_exc:
    ANOTHER_LIBRARY_IMPORT_ERROR = imp_exc
else:
    ANOTHER_LIBRARY_IMPORT_ERROR = None


# Later in plugin code, for example in __init__ of the plugin:

if ANOTHER_LIBRARY_IMPORT_ERROR:
    raise_from(
        AnsibleError('another_library must be installed to use this plugin'),
        ANOTHER_LIBRARY_IMPORT_ERROR)
    # If you target only newer Python 3 versions, you can also use the
    # 'raise ... from ...' syntax.

Ansible allows the following unchecked imports from these specific directories:

  • ansible-core:

    • For lib/ansible/modules/ and lib/ansible/module_utils/, unchecked imports are only allowed from the Python standard library;

    • For lib/ansible/plugins/, unchecked imports are only allowed from the Python standard library, from public dependencies of ansible-core, and from ansible-core itself;

  • collections:

    • For plugins/modules/ and plugins/module_utils/, unchecked imports are only allowed from the Python standard library;

    • For other directories in plugins/ (see the community collection requirements for a list), unchecked imports are only allowed from the Python standard library, from public dependencies of ansible-core, and from ansible-core itself.

Public dependencies of ansible-core are:

  • Jinja2

  • PyYAML

  • MarkupSafe (as a dependency of Jinja2)