{"id":7962,"library":"awxkit","title":"AWXKit","description":"The official command line interface for Ansible AWX, also providing a Python API for interacting with the AWX REST API. As of July 2024, AWXKit is actively maintained, with frequent releases aligning with the AWX project's fast-moving development cadence. The latest stable release is 24.6.1.","status":"active","version":"24.6.1","language":"en","source_language":"en","source_url":"https://github.com/ansible/awx","tags":["ansible","awx","automation","cli","api-client","redhat"],"install":[{"cmd":"pip install awxkit","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Requires Python >=3.8.","package":"python","optional":false},{"reason":"Core dependency for package distribution.","package":"setuptools","optional":false},{"reason":"awxkit is a client library for the AWX/Controller REST API; requires a running AWX instance.","package":"AWX (Ansible Automation Platform Controller)","optional":false}],"imports":[{"note":"Common top-level imports for both API interaction and CLI utilities.","symbol":"api, config, utils, cli","correct":"from awxkit import api, config, utils, cli"},{"note":"For direct interaction with the AWX API v2.","symbol":"ApiV2","correct":"from awxkit.api import ApiV2"},{"note":"To access AWX API resources programmatically.","symbol":"resources","correct":"from awxkit.api.resources import resources"},{"note":"Used for running AWX CLI commands programmatically.","symbol":"run","correct":"from awxkit.cli import run"}],"quickstart":{"code":"import os\nfrom awxkit.api import ApiV2, config\nfrom awxkit.api.resources import resources\nfrom awxkit.utils import PseudoNamespace\n\n# Configure AWX host and credentials\nconfig.base_url = os.environ.get('AWX_HOST', 'https://localhost:8043')\nconfig.credentials = PseudoNamespace({\n    'default': {\n        'username': os.environ.get('AWX_USERNAME', 'admin'),\n        'password': os.environ.get('AWX_PASSWORD', 'password'),\n        'insecure': os.environ.get('AWX_INSECURE_SSL', 'False').lower() == 'true'\n    }\n})\n\ntry:\n    # Load a session and get available API resources\n    session_connection = ApiV2().load_session().get()\n    api_resources = session_connection.get(resources)\n\n    print(f\"Successfully connected to AWX at: {config.base_url}\")\n    print(f\"Available API resources: {list(api_resources.keys())}\")\n\n    # Example: List all organizations\n    organizations = api_resources.organizations.get().results\n    print(f\"Found {len(organizations)} organizations:\")\n    for org in organizations:\n        print(f\" - {org.name} (ID: {org.id})\")\n\nexcept Exception as e:\n    print(f\"Error connecting to AWX: {e}\")\n    print(\"Please ensure AWX_HOST, AWX_USERNAME, AWX_PASSWORD, and AWX_INSECURE_SSL (optional) environment variables are set correctly.\")","lang":"python","description":"This quickstart demonstrates how to connect to an AWX instance using username/password authentication and list organizations. It uses environment variables for secure credential handling."},"warnings":[{"fix":"Review authentication code for JWT compatibility. If using username/password, explicitly configure `config.credentials` as shown in the quickstart or use OAuth2 tokens.","message":"Starting with AWXKit 24.0.0, JSON Web Tokens (JWT) became the default authentication method. This might require updates to existing authentication logic that relied on older defaults.","severity":"breaking","affected_versions":">=24.0.0"},{"fix":"Ensure your environment uses Python 3.11 or newer. Upgrade your Python interpreter if necessary.","message":"AWXKit 24.1.0 updated the required Python version from 3.9 to 3.11. Running on older Python versions (e.g., 3.9 or 3.10) may lead to unexpected errors or incompatibility issues.","severity":"breaking","affected_versions":">=24.1.0"},{"fix":"Avoid installing or upgrading to version 24.3.0. Use 24.3.1 or a later stable release.","message":"AWXKit version 24.3.0 was explicitly marked as 'DO NOT USE/UPGRADE' in its release notes due to critical issues.","severity":"gotcha","affected_versions":"24.3.0"},{"fix":"As a temporary workaround, use Python 3.11 or 3.12. Monitor GitHub issues for a permanent fix compatible with Python 3.13.","message":"Using awxkit with Python 3.13 can lead to `TypeError: HelpfulArgumentParser._parse_known_args()` or `AttributeError: 'CLI' object has no attribute 'verbose'` errors due to changes in Python's `argparse` module.","severity":"gotcha","affected_versions":">=24.6.1 (with Python 3.13)"},{"fix":"No direct fix for users; this requires an upstream update to use `importlib.metadata` instead.","message":"The `awxkit` library currently relies on the `pkg_resources` module, which is deprecated in modern Python versions and might lead to future compatibility issues or warnings.","severity":"deprecated","affected_versions":"All versions"},{"fix":"If using AWXKit in a production environment, consider moving to Red Hat Ansible Automation Platform for greater stability. For development or lab environments, be prepared for potential breaking changes and monitor AWX project updates closely.","message":"After version 24.6.1, AWX is undergoing significant architectural refactoring to a pluggable service-oriented design. This shift may introduce substantial breaking changes and impact stability, as semantic versioning is being replaced by CalVer.","severity":"breaking","affected_versions":">24.6.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Use a Python virtual environment with Python 3.11 or 3.12.","cause":"Incompatibility with Python 3.13's `argparse` module, which changed the signature of `_parse_known_args`.","error":"TypeError: HelpfulArgumentParser._parse_known_args() takes 3 positional arguments but 4 were given"},{"fix":"Revert to Python 3.11 or 3.12 until `awxkit` is updated for Python 3.13.","cause":"Similar to the `TypeError` above, this is another symptom of `awxkit`'s incompatibility with Python 3.13's `argparse` changes.","error":"AttributeError: 'CLI' object has no attribute 'verbose'"},{"fix":"Ensure `setuptools` is installed: `pip install setuptools`.","cause":"This error can occur if `setuptools` (which provides `pkg_resources`) is not correctly installed or if the Python environment is corrupted, especially in minimal container environments.","error":"ModuleNotFoundError: No module named 'pkg_resources'"},{"fix":"Verify that your `AWX_HOST` is correct and pointing to a valid AWX or Automation Controller instance. Ensure your AWX/Controller version is compatible with your `awxkit` version.","cause":"This usually indicates an issue where `awxkit` cannot properly fetch or interpret the API version information from the AWX/Controller host, possibly due to an outdated AWX/Controller version or an incorrect `base_url`.","error":"AttributeError: 'Api' object has no attribute 'available_versions'"},{"fix":"Downgrade your Python environment to Python 3.10 if this issue persists. Alternatively, use environment variables (`CONTROLLER_HOST`, `CONTROLLER_USERNAME`, etc.) instead of `--conf.*` flags if possible.","cause":"This specific error was reported when using `awxkit` CLI arguments with `--conf.*` in Python 3.11, suggesting an issue with how the `argparse` library handles conflicting subparsers in that Python version.","error":"Error: argument resource: conflicting subparser: config."}]}