Skip to main content

ansible-cleanup - Cleanup an Ansible project

Ansible-cleanup provides a command line tool to find and remove unused playbooks, tasks, group variables, and host variables. It maintains a clean codebase by recursively scanning your Ansible repository and listing files that are safe to delete.

Features

  • Identify unused playbooks and tasks: Scans the repository to find all unused playbooks and tasks. It analyzes the codebase and determines which playbooks and tasks are no longer referenced or used.
  • Find unused YAML files in group_vars and host_vars: Parses the "hosts" file, load all hosts and groups into a data structure. It then scans the group_vars and host_vars directories, identifying any YAML files that correspond to hosts or groups that no longer exist. This ensures that your variable files remain relevant and up-to-date.

Installation

Here is how to install ansible-cleanup using pip:

pip install --user git+https://github.com/jamescherti/ansible-cleanup

The pip command above will install the executable files in ~/.local/bin/.

Command Line Interface

The ansible-cleanup executable routes execution to specific cleanup modules using subcommands.

ansible-cleanup imports

This subcommand acts as a static code analyzer for your Ansible execution paths. It takes a root playbook (or multiple playbooks) as an argument and recursively traces every import_playbook, include_tasks, import_role, and related Ansible includes. It then compares the files it successfully resolved against all the YAML files in your repository to find the orphans.

As infrastructure evolves, old task files and sub-playbooks are often disconnected from the main execution tree but are left behind in the repository. Manually tracing YAML includes across dozens of files is tedious and prone to human error. This command automates the discovery of dead code, ensuring your repository only contains files that are actually executed.

Usage:

Pass your primary entry-point playbook (e.g., site.yml or main.yml) as an argument. The script will output the absolute paths of any .yml or .yaml files that are not referenced anywhere in the execution tree.

$ ansible-cleanup imports site.yaml
/path/to/repo/playbooks/old_deployment_tasks.yml
/path/to/repo/playbooks/deprecated_setup.yaml

ansible-cleanup vars

This subcommand manages your variable definitions. It reads your local hosts inventory file and builds a comprehensive list of all active hosts and groups. It then cross-references this active list against the files located in your host_vars and group_vars directories to find files named after hosts or groups that are not defined in the inventory.

When servers are decommissioned or host groups are renamed, engineers frequently remove them from the hosts file but forget to delete the corresponding variable files in host_vars/ or group_vars/. Over time, this leads to significant repository bloat and confusion over which variables are actually applied. This tool securely flags those forgotten files for deletion.

Execute the command in the directory containing your hosts file, host_vars directory, and group_vars directory. It requires no arguments.

Usage:

$ ansible-cleanup vars
/path/to/repo/host_vars/decommissioned-db-server-01.yml
/path/to/repo/group_vars/legacy-web-nodes.yaml

License

Copyright (c) 2009-2026 James Cherti

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Metadata

Release files for ansible-cleanup 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ansible-cleanup 1.0.0
File Size Uploaded Provenance Actions
ansible_cleanup-1.0.0.tar.gz 29.7 kB Without provenance Details for ansible_cleanup-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ansible-cleanup 1.0.0
File Interpreter ABI Platform Actions
ansible_cleanup-1.0.0-py3-none-any.whl Python 3 none any Details for ansible_cleanup-1.0.0-py3-none-any.whl

Total release size: 55.4 kB

Release files / ansible_cleanup-1.0.0.tar.gz

Download URL ansible_cleanup-1.0.0.tar.gz
Size 29.7 kB
Tags Source
SHA-256 checksum
How to use checksums
b8ccf38c2631877047aa629736886729203e2bde4c3851e8c88c6951e683208b
BLAKE2b-256 checksum
How to use checksums
4603381cf396f1eb4816990a02f2e68989abdff00f86fa36ca4f990c48fe54a7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / ansible_cleanup-1.0.0-py3-none-any.whl

Download URL ansible_cleanup-1.0.0-py3-none-any.whl
Size 25.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
96c3617e29d73ec4204eab82ff2e9f0eca8b09e3bbbf027ed86672af4807f65a
BLAKE2b-256 checksum
How to use checksums
008f865195f33b2b5cd072c6e7e88c8072ecdc8f849922bbd89a5cc3e523f31e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Security for ansible-cleanup 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page