Skip to main content

Comicbox

PyPI Python License Docs

Comicbox is a Python library and command line tool that reads, writes, and synthesizes comic book archive metadata. It understands every popular comic metadata standard, merges them into one consistent data model, converts between them, tags comics from online databases, and extracts pages and covers.

It is the metadata engine behind the Codex comic reader, but works just as well as a standalone command line tool for organizing a comic library.

✨ What Comicbox Does

  • Reads many archive types — CBZ, CBR, CBT, CB7, and (optionally) PDF.
  • Reads and writes every popular metadata standard — ComicInfo.xml, MetronInfo.xml, ComicBookInfo, CoMet, PDF metadata, and its own YAML/JSON.
  • Merges every source into one model — combines metadata from each embedded format and the filename into a single normalized view, then writes it back out to whichever formats you choose.
  • Tags comics online — looks up and matches comics against Metron and ComicVine, then writes the result.
  • Converts archives — repacks CBR/CBT/CB7 (and comic PDFs) to CBZ, and translates metadata between formats.
  • Extracts images — pulls cover art or arbitrary page ranges out of any supported archive.
  • Is scriptable and embeddable — a rich CLI, a Python API, and published JSON Schemas for every format.

📚 Archive Formats

Format Read Write
CBZ (zip) ✅ ✅
CBR (rar) ✅ converts to CBZ
CBT (tar) ✅ converts to CBZ
CB7 (7z) ✅ converts to CBZ
PDF ✅ ✅ embedded metadata

CBR extraction and conversion require the unrar binary on your PATH. PDF support is an optional extra.

🏷️ Metadata Formats

Comicbox reads and writes all of the following, normalizing each into a common schema:

Format Read Write Notes
ComicInfo.xml (ComicRack) ✅ ✅ v2.1 (draft) schema
MetronInfo.xml ✅ ✅ v1.1 schema
ComicBookInfo (Comic Book Lover) ✅ ✅ archive comment JSON
CoMet ✅ ✅
PDF metadata ✅ ✅ can embed ComicInfo.xml / MetronInfo.xml
Comicbox YAML / JSON ✅ ✅ native, lossless
Filename ✅ — parses metadata out of the file name

A full cross-format tag translation table is available.

🔀 One Unified Metadata Model

Different formats spell the same idea in different ways. Comicbox reconciles them so you never have to:

  • Identifiers — IDs, GTINs, and URLs from every format are aggregated into a single identifiers structure, and written back out as URNs in the Notes field.
  • Reprints — Alternate Names, Aliases, and "is version of" relationships collapse into one reprints list.
  • Notes mining — the heavily-abused Notes field is parsed for embedded data (tagger, timestamps, and identifiers) that formats don't otherwise carry.
  • Liberal value parsing — fuzzy, caseless values for enum-like fields (Age Rating, Format, credit roles) are accepted, tidied to Title Case, and converted to each output format's own enum on write.
  • Filename parsing — series, issue, year, and more are extracted from a wide variety of naming conventions via comicfn2dict.

🌐 Online Tagging

Comicbox can identify a comic and tag it from an online database. Metron and ComicVine are supported. It searches by the series, issue, and year it knows about, ranks candidates, breaks close calls with cover-image matching, and writes the best result.

# Interactive: prompts only when the match isn't clear.
comicbox -o metron "GI Joe #007 (1952).cbz"

# Tag by an exact database id (skips searching).
comicbox -I metron:42 "comic.cbz"

# Unattended batch run: never prompts, 4 files at a time.
comicbox --online all --recurse --prompts never -j 4 ./comics/

--match controls how confidently comicbox writes without asking (ask · careful · auto · eager), and --effort (minimal · balanced · thorough) trades matching accuracy for fewer API calls on fan-out sources like ComicVine — Metron doesn't fan out, so it ignores effort and always searches at full strength. Credentials come from --auth, COMICBOX_* environment variables, the config file, or your system keyring. Metron authenticates with an API token generated on your metron.cloud account page — pass it as --auth metron:TOKEN or COMICBOX_METRON_KEY. ComicVine takes its key the same way, as --auth comicvine:KEY. A Metron username and password still work but are deprecated and will be removed in a future release. See comicbox -h for the full set of online, caching, and tuning options.

🖼️ Pages, Covers & Conversion

# Extract the cover image.
comicbox -X --dest-path ./out "comic.cbz"

# Extract a range of pages (zero-based) by index.
comicbox -x 0:5 --dest-path ./out "comic.cbz"

# Convert a CBR to a CBZ, carrying metadata across.
comicbox -z "comic.cbr"

# Convert a single-image-per-page comic PDF to CBZ without re-encoding.
comicbox --cbz --pdf-pages image "comic.pdf"

# Rename a file to comicbox's canonical filename format.
comicbox --rename "comic.cbz"

📦 Installation

pip install comicbox

For PDF support, install the pdf extra:

pip install comicbox[pdf]

Dependencies

Comicbox needs no binary dependencies for CBZ, CBT, and CB7. Reading or converting CBR archives requires the unrar binary on your PATH.

The optional PDF extra pulls in pymupdf, which ships wheels with a bundled libmupdf for most platforms. Some platforms (e.g. Linux on ARM) may need libstdc++ plus C/C++ build tools to compile it.

Installing on ARM (AARCH64)

pymupdf has no pre-built AARCH64 wheels, so pip must build it. On some Python versions the build fails unless this environment variable is set:

PYMUPDF_SETUP_PY_LIMITED_API=0 pip install comicbox[pdf]

You will also need the build-essential and python3-dev (or equivalent) packages.

⌨️ Command Line

Comicbox ships a thorough, self-documenting CLI. Run:

comicbox -h

for the complete reference, including every metadata format key, the --print phases, and the online tagging tables. A few representative commands:

# Print the merged metadata comicbox reads from a comic.
comicbox -p "comic.cbz"

# Set a field and write it as ComicInfo.xml inside the archive.
comicbox -m "{publisher: SmallComics}" -w cix "comic.cbz"

# Recursively set a field across an entire library.
comicbox --recurse -m "{publisher: 'SC Comics'}" -w cix ./comics/

# Export and re-import metadata as a file.
comicbox -e cix "comic.cbz"
comicbox -i ComicInfo.xml -w cix "comic.cbz"

-m/--metadata accepts a compact "linear YAML" using tag names from any of the supported formats. Put a space after each colon so it parses as YAML, and quote values containing YAML special characters (:[]{},). See comicbox -h for many more -m examples, and "escaping YAML" for the escaping details.

💡 Preview before writing. Add -p to print exactly what would be written, or -n/--dry-run to perform an action without touching the filesystem.

Editing or Deleting Metadata

The cleanest way to edit or remove existing tags is to round-trip through a file:

# 1. Export the current metadata to an editable file.
comicbox --export cix "My Overtagged Comic.cbz"

# 2. Edit it.
nvim ComicInfo.xml

# 3. Preview the re-import.
comicbox --import ComicInfo.xml -p "My Overtagged Comic.cbz"

# 4. Wipe the old tags, then write the edited file back (careful!).
comicbox --delete-all-tags "My Overtagged Comic.cbz"
comicbox --import ComicInfo.xml -w cix "My Overtagged Comic.cbz"

You can also drop individual keys with -D/--delete-keys using dotted glom paths, e.g. -D series,reprints.0.series.

🛠 API

Comicbox is primarily a library. The Comicbox class in comicbox.box is the main read interface, and comicbox.write exposes a documented write API. Auto-generated API docs are published with the HTML docs.

from comicbox.box import Comicbox

with Comicbox("comic.cbz") as cb:
    metadata = cb.to_dict()  # merged, normalized metadata
    file_type = cb.get_file_type()  # "CBZ", "PDF", ...
    mtime = cb.get_metadata_mtime()  # last metadata modification time
    cover = cb.get_cover_page()  # cover image bytes

Writing is done through the public write_metadata (single file) and bulk_write (batched) helpers:

from comicbox.write import write_metadata

result = write_metadata(
    "comic.cbz",
    # The patch is the contents under the "comicbox" root tag. The
    # root-wrapped dict Comicbox.to_dict() returns is also accepted.
    {"publisher": {"name": "SmallComics"}, "genres": ["Science Fiction"]},
    formats=["COMIC_INFO"],  # MetadataFormats names; e.g. COMIC_INFO, METRON_INFO
)
print(result.written)

Every operational error these APIs raise derives from comicbox.exceptions.ComicboxError — ArchiveError, ArchiveWriteError, MetadataError, ExportError, WriteValidationError, OnlineConfigurationError, OnlineLookupAbortedError, and UnsupportedArchiveTypeError — so consumers can except ComicboxError without swallowing unrelated programming errors.

⚙️ Configuration

Comicbox is configured by command line arguments, an optional config file, and environment variables (in that order of precedence).

  • Defaults live in config_default.yaml, which also documents the nested config groups (general, read, write, convert, compute, and online).
  • Config file — point at one with -c PATH, or place it at ~/.config/comicbox/config.yaml.
  • Environment variables are prefixed with COMICBOX_.
  • Log level is set with the LOGLEVEL environment variable:
LOGLEVEL=ERROR comicbox -p "comic.cbz"

Installing comicbox also installs two small sibling libraries, each usable on its own:

  • comicfn2dict — parses metadata out of comic filenames into Python dicts (also used by ComicTagger).
  • pdffile — presents a ZipFile-like interface for PDF files (installed with the [pdf] extra).

📜 Documentation

🛠 Development

Comicbox is hosted on GitHub. Most development tasks are driven by the Makefile — run make to see what's available.

The DEBUG_TRANSFORM environment variable prints verbose schema-transform information, useful when debugging format conversions.

📄 License

Comicbox is licensed under the LGPL-3.0-only license.

Metadata

Release files for comicbox 4.8.5

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

Source distribution (sdist)

Source distribution for comicbox 4.8.5
File Size Uploaded Provenance Actions
comicbox-4.8.5.tar.gz 1.0 MB Without provenance Details for comicbox-4.8.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for comicbox 4.8.5
File Interpreter ABI Platform Actions
comicbox-4.8.5-py3-none-any.whl Python 3 none any Details for comicbox-4.8.5-py3-none-any.whl

Total release size: 1.4 MB

Release files / comicbox-4.8.5.tar.gz

Download URL comicbox-4.8.5.tar.gz
Size 1.0 MB
Tags Source
SHA-256 checksum
How to use checksums
d133951754a0d4f54a4b766b82768148f97e8de369e20da8892151017aa2f044
BLAKE2b-256 checksum
How to use checksums
52adc25e8a3d798dcaa20589912c9099c2456ec8a78f7808d5d616bde3fc1875
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / comicbox-4.8.5-py3-none-any.whl

Download URL comicbox-4.8.5-py3-none-any.whl
Size 346.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0a0baf8b0f0a5e0695aeaf31142ef6fb8ef9b9721c601f1d9fb180d4b976b51f
BLAKE2b-256 checksum
How to use checksums
66a15b8c70ad25d2bf47a35e8be42c4a959a409219794dce2f8ce3243d902385
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for comicbox 4.8.5

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

4.8.5 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