https://github.com/hyugogirubato/cbz
CBZ simplifies creating, managing, and viewing comic book files in CBZ, CBR, and PDF formats, offering seamless packaging, metadata handling and built-in viewing capabilities.
https://github.com/hyugogirubato/cbz
cbr cbz comics ebooks manga pdf python webtoons
Last synced: about 2 hours ago
JSON representation
CBZ simplifies creating, managing, and viewing comic book files in CBZ, CBR, and PDF formats, offering seamless packaging, metadata handling and built-in viewing capabilities.
- Host: GitHub
- URL: https://github.com/hyugogirubato/cbz
- Owner: hyugogirubato
- License: mit
- Created: 2022-08-30T12:45:10.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-07-26T15:22:33.000Z (3 months ago)
- Last Synced: 2025-07-26T20:07:43.014Z (3 months ago)
- Topics: cbr, cbz, comics, ebooks, manga, pdf, python, webtoons
- Language: Python
- Homepage: https://pypi.org/project/cbz/
- Size: 33.4 MB
- Stars: 33
- Watchers: 1
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# CBZ
CBZ is a Python library designed for creating, manipulating, and viewing comic book files in CBZ, CBR, and PDF formats. It offers a straightforward interface to pack comic pages into CBZ archives, extract metadata from CBZ and CBR files, and display comics using a built-in player.
## Features
- 🚀 Seamless Installation via [pip](#installation)
- 📚 Pack images into CBZ format for comics and manga
- 📝 Extract and manage title, series, format, and more
- 🖼️ Handle comic pages with attributes like type and format
- 📦 Unpack CBZ and CBR files to retrieve comic information, or extract images from PDF files
- 🛠️ Built-in player for viewing CBZ, CBR, and PDF comics
- 📚 Full CBR (RAR) format support for reading existing archives
- ❤️ Fully Open-Source! Pull Requests Welcome
## Installation
Install CBZ from PyPI using pip:
```shell
pip install cbz
```
## Quick Start
Here's a quick example of how to create a CBZ file from a series of images:
````python
from pathlib import Path
from cbz.comic import ComicInfo
from cbz.constants import PageType, YesNo, Manga, AgeRating, Format
from cbz.page import PageInfo
PARENT = Path(__file__).parent
if __name__ == '__main__':
paths = list(Path('path/to/your/images').iterdir())
# Load each page from the 'images' folder into a list of PageInfo objects
pages = [
PageInfo.load(
path=path,
type=PageType.FRONT_COVER if i == 0 else PageType.BACK_COVER if i == len(paths) - 1 else PageType.STORY
)
for i, path in enumerate(paths)
]
# Create a ComicInfo object using ComicInfo.from_pages() method
comic = ComicInfo.from_pages(
pages=pages,
title='Your Comic Title',
series='Your Comic Series',
number=1,
language_iso='en',
format=Format.WEB_COMIC,
black_white=YesNo.NO,
manga=Manga.NO,
age_rating=AgeRating.PENDING
)
# Show the comic using the show()
comic.show()
# Pack the comic book content into a CBZ file format
cbz_content = comic.pack()
# Define the path where the CBZ file will be saved
cbz_path = PARENT / 'your_comic.cbz'
# Write the CBZ content to the specified path
cbz_path.write_bytes(cbz_content)
````
## Player
CBZ includes a command-line player for viewing comic book files in multiple formats. Simply run `cbzplayer ` to launch the player with the specified comic book file.
### Supported Formats
- **CBZ** (Comic Book ZIP) - Standard ZIP archives containing images and metadata
- **CBR** (Comic Book RAR) - RAR archives containing images and metadata
- **PDF** - Portable Document Format files with embedded images (images only, no metadata)
### Usage
````shell
usage: cbzplayer [-h]
Launch CBZ player with a comic book file
positional arguments:
Path to the CBZ, CBR, or PDF comic book file.
options:
-h, --help show this help message and exit
````
### Examples
```shell
# View a CBZ file
cbzplayer my_comic.cbz
# View a CBR file
cbzplayer my_comic.cbr
# View a PDF file
cbzplayer my_comic.pdf
```
### Requirements for CBR Support
CBR file support requires:
- The `rarfile` Python package (automatically installed with CBZ)
- An external RAR extraction tool such as:
- `unrar` (recommended) - Available in most package managers
- `rar` - Commercial RAR archiver
- `7zip` - Free alternative with RAR support
For installation instructions and compatibility details, see the [rarfile documentation](https://github.com/markokr/rarfile).
## Detailed Usage
### Creating a ComicInfo Object
The `ComicInfo` class represents a comic book with metadata and pages. It supports initialization from a list of `PageInfo` objects:
```python
from cbz.comic import ComicInfo
from cbz.constants import PageType, YesNo, Manga, AgeRating, Format
from cbz.page import PageInfo
# Example usage:
pages = [
PageInfo.load(path='/path/to/page1.jpg', type=PageType.FRONT_COVER),
PageInfo.load(path='/path/to/page2.jpg', type=PageType.STORY),
PageInfo.load(path='/path/to/page3.jpg', type=PageType.BACK_COVER),
]
comic = ComicInfo.from_pages(
pages=pages,
title='My Comic',
series='Comic Series',
number=1,
language_iso='en',
format=Format.WEB_COMIC,
black_white=YesNo.NO,
manga=Manga.NO,
age_rating=AgeRating.PENDING
)
```
### Extracting Metadata
Retrieve comic information as a dictionary using `get_info()`:
```python
info = comic.get_info()
print(info)
```
### Packing into CBZ Format
Pack the comic into a CBZ file format:
```python
cbz_content = comic.pack()
```
### Loading from Different Formats
Load a comic from an existing CBZ file (with metadata):
```python
comic_from_cbz = ComicInfo.from_cbz('/path/to/your_comic.cbz')
```
Load a comic from an existing CBR file (with metadata):
```python
comic_from_cbr = ComicInfo.from_cbr('/path/to/your_comic.cbr')
```
Load a comic from a PDF file (images only, no metadata):
```python
comic_from_pdf = ComicInfo.from_pdf('/path/to/your_comic.pdf')
```
**Notes**:
- CBR support requires an external RAR extraction tool. For detailed compatibility information and advanced configuration, see the [rarfile documentation](https://github.com/markokr/rarfile).
- PDF files only provide image content; comic metadata (title, series, etc.) is not available from PDF files.
## Contributors
## Licensing
This software is licensed under the terms of [MIT License](https://github.com/hyugogirubato/cbz/blob/main/LICENSE).
You can find a copy of the license in the LICENSE file in the root folder.
### Third-Party Licenses
This project uses the following third-party libraries:
- **[langcodes](https://pypi.org/project/langcodes/)** - MIT License
- **[Pillow](https://pypi.org/project/Pillow/)** - HPND License
- **[pillow-avif-plugin](https://pypi.org/project/pillow-avif-plugin/)** - MIT License
- **[pillow-jxl-plugin](https://pypi.org/project/pillow-jxl-plugin/)** - MIT License
- **[pypdf](https://pypi.org/project/pypdf/)** - BSD License
- **[rarfile](https://pypi.org/project/rarfile/)** - ISC License
- **[xmltodict](https://pypi.org/project/xmltodict/)** - MIT License
---
© hyugogirubato 2025