docker-image-cleanup 0.1.0__tar.gz

docker_image_cleanup-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.3
+Name: docker-image-cleanup
+Version: 0.1.0
+Summary: Clean up old Docker images from local storage with retention controls
+Keywords: docker,cleanup,images,disk-space
+Author: Michael Bianco
+Author-email: Michael Bianco <mike@mikebian.co>
+Requires-Dist: click>=8.3.0
+Requires-Dist: docker>=7.1.0
+Requires-Dist: structlog-config==0.6.0
+Requires-Dist: whenever>=0.9.3
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/iloveitaly/docker-image-cleanup
+Description-Content-Type: text/markdown
+
+# Clean Up Images from Self-Hosted Docker Registries
+
+If you're running a self-hosted Docker registry (using tools like [unregistry](https://github.com/psviderski/unregistry)), you'll want to clean up old images to reclaim disk space. This tool connects to your local Docker daemon and removes old images from specified repositories while keeping the ones you actually need.
+
+The cleanup logic is simple: keep your N most recent images and anything built in the last M days. Everything else gets removed. Images currently in use by containers are automatically skipped.
+
+This tool is designed for managing images from self-hosted registries and probably shouldn't be used for general local Docker cleanup.
+
+## Installation
+
+```bash
+pip install docker-image-cleanup
+```
+
+Or using `uv`:
+
+```bash
+uv tool install docker-image-cleanup
+```
+
+## Usage
+
+The basic command takes one or more image repositories:
+
+```bash
+docker-image-cleanup myrepo/myimage
+```
+
+You can clean multiple repositories at once:
+
+```bash
+docker-image-cleanup myrepo/image1 myrepo/image2
+```
+
+Before running the cleanup for real, use `--dry-run` to see what would be removed:
+
+```bash
+docker-image-cleanup --dry-run myrepo/myimage
+```
+
+Adjust the retention policy with `--num-recent` and `--min-age-days`:
+
+```bash
+# Keep only the 3 most recent images
+docker-image-cleanup --num-recent 3 myrepo/myimage
+
+# Keep images from the last 7 days
+docker-image-cleanup --min-age-days 7 myrepo/myimage
+
+# Combine both options
+docker-image-cleanup --num-recent 3 --min-age-days 7 myrepo/myimage
+```
+
+## Features
+
+- Removes old Docker images based on age and recency criteria
+- Keeps a configurable number of recent images (default: 5)
+- Preserves images newer than a specified age threshold (default: 30 days)
+- Automatically skips images currently in use by containers
+- Dry-run mode to preview changes before execution
+- Human-readable disk space savings reporting
+- Structured logging for detailed operation visibility
+
+## How It Works
+
+The cleanup process is straightforward:
+
+1. Lists all images for the specified repository
+2. Identifies images to keep based on retention criteria (most recent N images and images newer than M days)
+3. Removes or untags images that don't meet retention criteria
+4. Skips any images currently in use by containers
+5. Reports total disk space saved
+
+Images with multiple tags are handled intelligently. If all tags on an image would be removed, the entire image is deleted. If only some tags would be removed, those tags are untagged but the image remains.
+
+## Requirements
+
+- Python 3.11+
+- Docker daemon running locally
+- Docker Python SDK
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/iloveitaly/docker-image-cleanup
+cd docker-image-cleanup
+
+# Install dependencies
+uv sync
+
+# Run tests
+pytest
+
+# Run the CLI
+uv run docker-image-cleanup --help
+```
+
+# [MIT License](LICENSE.md)

docker_image_cleanup-0.1.0/README.md

@@ -0,0 +1,99 @@
+# Clean Up Images from Self-Hosted Docker Registries
+
+If you're running a self-hosted Docker registry (using tools like [unregistry](https://github.com/psviderski/unregistry)), you'll want to clean up old images to reclaim disk space. This tool connects to your local Docker daemon and removes old images from specified repositories while keeping the ones you actually need.
+
+The cleanup logic is simple: keep your N most recent images and anything built in the last M days. Everything else gets removed. Images currently in use by containers are automatically skipped.
+
+This tool is designed for managing images from self-hosted registries and probably shouldn't be used for general local Docker cleanup.
+
+## Installation
+
+```bash
+pip install docker-image-cleanup
+```
+
+Or using `uv`:
+
+```bash
+uv tool install docker-image-cleanup
+```
+
+## Usage
+
+The basic command takes one or more image repositories:
+
+```bash
+docker-image-cleanup myrepo/myimage
+```
+
+You can clean multiple repositories at once:
+
+```bash
+docker-image-cleanup myrepo/image1 myrepo/image2
+```
+
+Before running the cleanup for real, use `--dry-run` to see what would be removed:
+
+```bash
+docker-image-cleanup --dry-run myrepo/myimage
+```
+
+Adjust the retention policy with `--num-recent` and `--min-age-days`:
+
+```bash
+# Keep only the 3 most recent images
+docker-image-cleanup --num-recent 3 myrepo/myimage
+
+# Keep images from the last 7 days
+docker-image-cleanup --min-age-days 7 myrepo/myimage
+
+# Combine both options
+docker-image-cleanup --num-recent 3 --min-age-days 7 myrepo/myimage
+```
+
+## Features
+
+- Removes old Docker images based on age and recency criteria
+- Keeps a configurable number of recent images (default: 5)
+- Preserves images newer than a specified age threshold (default: 30 days)
+- Automatically skips images currently in use by containers
+- Dry-run mode to preview changes before execution
+- Human-readable disk space savings reporting
+- Structured logging for detailed operation visibility
+
+## How It Works
+
+The cleanup process is straightforward:
+
+1. Lists all images for the specified repository
+2. Identifies images to keep based on retention criteria (most recent N images and images newer than M days)
+3. Removes or untags images that don't meet retention criteria
+4. Skips any images currently in use by containers
+5. Reports total disk space saved
+
+Images with multiple tags are handled intelligently. If all tags on an image would be removed, the entire image is deleted. If only some tags would be removed, those tags are untagged but the image remains.
+
+## Requirements
+
+- Python 3.11+
+- Docker daemon running locally
+- Docker Python SDK
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/iloveitaly/docker-image-cleanup
+cd docker-image-cleanup
+
+# Install dependencies
+uv sync
+
+# Run tests
+pytest
+
+# Run the CLI
+uv run docker-image-cleanup --help
+```
+
+# [MIT License](LICENSE.md)

docker_image_cleanup-0.1.0/docker_image_cleanup/__init__.py

@@ -0,0 +1,132 @@
+import click
+import docker
+import docker.errors
+import structlog
+from collections import defaultdict
+from whenever import Instant
+from structlog_config import configure_logger
+
+configure_logger()
+log = structlog.get_logger()
+
+
+def human_size(size_bytes):
+    size = size_bytes
+    for unit in ["B", "KB", "MB", "GB", "TB"]:
+        if size < 1024:
+            return f"{size:.2f} {unit}"
+        size /= 1024
+    return f"{size:.2f} PB"
+
+
+def clean_repo(client, image_repo, num_recent, min_age_days, dry_run, now):
+    images = client.images.list(name=image_repo)
+    if not images:
+        log.info("no images", repo=image_repo)
+        return 0
+
+    sorted_images = sorted(
+        images, key=lambda img: Instant.parse_iso(img.attrs["Created"]), reverse=True
+    )
+
+    keep_tags = set()
+    for img in sorted_images[:num_recent]:
+        keep_tags.update(img.tags)
+
+    min_age = now.subtract(hours=min_age_days * 24)
+    for img in images:
+        created = Instant.parse_iso(img.attrs["Created"])
+        log.debug("inspecting image", image_id=img.id, tags=img.tags, created=created)
+        if created >= min_age:
+            keep_tags.update(img.tags)
+
+    tags_to_remove = []
+    for img in images:
+        for tag in img.tags:
+            if tag not in keep_tags and tag.startswith(image_repo + ":"):
+                tags_to_remove.append((tag, img))
+
+    remove_by_id = defaultdict(list)
+    for tag, img in tags_to_remove:
+        remove_by_id[img.id].append(tag)
+
+    total_saved = 0
+    for img_id, remove_tags in remove_by_id.items():
+        img = client.images.get(img_id)
+        all_tags = img.tags
+        if set(remove_tags) == set(all_tags):
+            in_use = (
+                len(client.containers.list(all=True, filters={"ancestor": img_id})) > 0
+            )
+            if in_use:
+                log.warning("skipped image in use", image_id=img_id, tags=remove_tags)
+                continue
+            size = img.attrs.get("Size", 0)
+            if dry_run:
+                log.info(
+                    "would remove image",
+                    image_id=img_id,
+                    tags=remove_tags,
+                    size=human_size(size),
+                )
+            else:
+                for tag in remove_tags:
+                    client.images.remove(tag, force=False)
+                log.info(
+                    "removed image",
+                    image_id=img_id,
+                    tags=remove_tags,
+                    size=human_size(size),
+                )
+            total_saved += size
+        else:
+            if dry_run:
+                log.info("would untag", tags=remove_tags)
+            else:
+                for tag in remove_tags:
+                    try:
+                        client.images.remove(tag, force=False)
+                        log.info("untagged", tag=tag)
+                    except docker.errors.APIError as e:
+                        log.warning("skipped untag", tag=tag, reason=str(e))
+
+    msg = "total space that would be saved" if dry_run else "total space saved"
+    log.info(msg, bytes=total_saved, human=human_size(total_saved))
+    return total_saved
+
+
+@click.command()
+@click.argument("image_repos", nargs=-1, required=True)
+@click.option(
+    "--num-recent", default=5, help="Number of recent tags to keep.", show_default=True
+)
+@click.option(
+    "--min-age-days",
+    default=30,
+    help="Minimum age in days to keep tags.",
+    show_default=True,
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Simulate removal without executing.",
+    show_default=True,
+)
+def main(image_repos, num_recent, min_age_days, dry_run):
+    client = docker.from_env()
+    now = Instant.now()
+
+    grand_total = 0
+    for image_repo in image_repos:
+        log.info("cleaning repo", repo=image_repo)
+        grand_total += clean_repo(
+            client, image_repo, num_recent, min_age_days, dry_run, now
+        )
+
+    if len(image_repos) > 1:
+        msg = (
+            "grand total space that would be saved"
+            if dry_run
+            else "grand total space saved"
+        )
+        log.info(msg, bytes=grand_total, human=human_size(grand_total))

docker_image_cleanup-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "docker-image-cleanup"
+version = "0.1.0"
+description = "Clean up old Docker images from local storage with retention controls"
+keywords = ["docker", "cleanup", "images", "disk-space"]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.3.0",
+    "docker>=7.1.0",
+    "structlog-config==0.6.0",
+    "whenever>=0.9.3",
+]
+authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
+urls = { "Repository" = "https://github.com/iloveitaly/docker-image-cleanup" }
+
+# additional packaging information: https://packaging.python.org/en/latest/specifications/core-metadata/#license
+[project.scripts]
+docker-image-cleanup = "docker_image_cleanup:main"
+
+[build-system]
+requires = ["uv_build>=0.8.11,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# avoids the src/ directory structure
+module-root = ""
+
+[dependency-groups]
+dev = ["pytest>=8.3.3","pyright>=1.1.380","ruff>=0.8.0"]
+