📦 ConvertToCBZ

Convert folders of images and comic archives into the CBZ format used by every major comic/manga reader.

---

---

Features

🖼️ Image folders	Packs any folder of images into a .cbz named after the folder
📁 Archives	Re-packs .rar, .zip, .7z, .cbr, .cb7 into .cbz
📂 Two modes	Output folder — originals untouched; In-place — originals deleted after conversion
🔍 DryRun	Preview exactly what would happen without touching any file
🔄 Recursive	Scans all sub-folders, processes deepest first
🚫 Ignore folders	Specify folder names to skip entirely at any depth (e.g. thumbs)
🗂️ Smart unwrap	If an archive contains a single wrapper folder, its contents are lifted to root level before repacking
💥 Atomic writes	CBZ is written to a temp file then renamed — a crash never leaves a corrupt partial file
🧵 Threaded	GUI stays responsive; includes a real-time color-coded log and progress bar
⛔ Stop button	Graceful cancellation after the current file finishes
🐍 Scriptable	run_conversion() public API for headless use

---

Supported Formats

Input	Output
Image folders (.jpg .jpeg .png .gif .webp .bmp .tiff .tif .avif)	.cbz
Archives (.rar .zip .7z .cbr .cb7)	.cbz

---

Requirements

• Windows 10 or 11
• Python 3.10+ — python.org
• 7-Zip — 7-zip.org (must be installed; standard path or on PATH)

---

Installation

git clone https://github.com/YOUR_USERNAME/ConvertToCBZ.git
cd ConvertToCBZ
pip install -r requirements.txt

---

Usage

GUI (recommended)

Double-click ConvertToCBZ.bat — opens the GUI with no console window.

Or start manually:

python gui.py

Steps:

1. Click Browse to select the source folder containing your images or archives.
2. Optionally select an output folder — leave empty to enable in-place mode.
3. Optionally tick DryRun to simulate without writing anything.
4. Optionally add ignored folder names via the + Add folder button — any folder whose name matches (at any depth) will be skipped entirely. thumbs is ignored by default.
5. Click ▶ START.

A live log shows progress. Use ⬛ STOP to cancel gracefully.
After a successful run the 📂 Open folder button appears.

---

Command-line (Python API)

from converter import run_conversion

stats = run_conversion(
    source_path=r"D:\Manga",
    dest_path=r"D:\Manga_CBZ",   # empty string "" = in-place mode
    dry_run=False,
    log_fn=print,
    ignored_folders=["thumbs", ".cache"],
)

print(f"Converted: {stats.images_converted} folders, {stats.archives_converted} archives")

run_conversion signature:

def run_conversion(
    source_path: str,
    dest_path: str,
    dry_run: bool,
    log_fn: Callable[[str, str], None],
    progress_fn: Callable[[int, int, str], None] | None = None,
    stop_event: threading.Event | None = None,
    ignored_folders: list[str] | None = None,
) -> ConversionStats:

ignored_folders is matched case-insensitively against every component of each folder's path relative to source_path. Any folder whose name (or any ancestor's name) appears in the list is skipped in full.

---

How It Works

1. The source directory is scanned recursively; folders are collected deepest first so sub-chapters are processed before the parent.
2. Folders whose name (or any ancestor's name within the source tree) matches an entry in ignored_folders are skipped before any work is done on them.
3. For each remaining folder:
   • Images → packed into a .cbz named after the folder.
   • Archives → extracted to a temp directory via 7-Zip, unwrapped if needed, repacked as .cbz.
4. CBZ files are stored with no compression (ZIP_STORED) — standard practice because images are already compressed.
5. The original directory structure is mirrored in the output folder.
6. Name collisions (a folder and an archive with the same stem) are detected and reported in the log.

---

Project Structure

ConvertToCBZ/
├── gui.py               # CustomTkinter GUI application
├── converter.py         # Core conversion logic (public API: run_conversion)
├── ConvertToCBZ.bat     # Double-click launcher (no console window)
├── requirements.txt     # Python dependencies
├── CHANGELOG.md
└── README.md

---

FAQ

Q: Why does the tool require 7-Zip?
A: Python's built-in zipfile cannot read .rar or .cbr files. 7-Zip handles all archive formats consistently and is free.

Q: What if 7-Zip is not installed in the default path?
A: The tool also searches your system PATH (covers winget, Chocolatey, Scoop installs). The GUI shows a live indicator and re-checks every 5 seconds.

Q: Will my originals be safe?
A: In Output folder mode, originals are never modified. In In-place mode, originals are deleted after a successful conversion — a failed conversion leaves the original untouched.

Q: The output CBZ already exists. Will it be overwritten?
A: No — existing CBZ files are skipped and reported as Skip (exists) in the log.

Q: Can I run this without the GUI?
A: Yes — import and call run_conversion() directly (see the API example above).

Q: How does folder ignoring work exactly?
A: The check is name-based, not path-based. If you ignore thumbs, then Manga/Vol1/thumbs/, Manga/thumbs/, and any other folder named thumbs at any depth will all be skipped — including their subfolders. Matching is case-insensitive.

---

Contributing

Issues and pull requests are welcome.

1. Fork the repository.
2. Create a branch: git checkout -b feature/my-feature.
3. Commit your changes: git commit -m "Add my feature".
4. Push: git push origin feature/my-feature.
5. Open a Pull Request.

Please keep code in English only (comments, variable names, log messages).

---

License

MIT