epub-image-helper
This tool allows you to easily convert specified photos and images into EPUB e-book format, making it accessible for family and friends. It can be used to create monthly or yearly photo collections for children and transform travel photos into e-books.
Note
% cat requirements.txt
#EbookLib==0.18
#git+https://github.com/changyy/ebooklib.git@release#egg=EbookLib
#EbookLib @ git+https://github.com/changyy/ebooklib.git@release
EbookLib.changyy==0.18.2023.1221.0
lxml==4.9.3
Pillow==10.1.0
PyMuPDF==1.23.7
PyMuPDFb==1.23.7
six==1.16.0
This tool relies on the Python library EbookLib to create EPUB format files.
However, currently, ebooklib v0.18 still has some features that need enhancement. Pull requests (PRs) have been created and are awaiting review by the original author. In the meantime, an alternative solution has been implemented using the ebooklib.changyy package. Once the required features for the future are integrated, it will be possible to switch back to the original ebooklib.
More info:
- https://github.com/aerkalov/ebooklib/pulls
- https://pypi.org/project/EbookLib.changyy/
- https://github.com/changyy/ebooklib/tree/release
Quick test
Convert a PDF file consisting entirely of images to an EPUB file consisting entirely of images
% epub-image-helper | jq -r '.version'
1.0.4
% mkdir /tmp/test-pdf-workdir
% ls /tmp/input.pdf
/tmp/input.pdf
% python3 -c 'from epub_image_helper.testPdf2Epub import testPdf2Epub ; testPdf2Epub(inputFile="/tmp/input.pdf", outputFile="/tmp/output.epub", tmpWorkDir="/tmp/test-pdf-workdir")'
{
"status": true,
...
"output": {
"path": "/tmp/output.epub",
"size": 140028568,
"sizeReadable": "133.54 MB",
"imageCount": 0,
"timeCost": [
3.0279159545898438e-05,
44.72491812705994,
2.896683931350708
]
},
"error": [],
"version": "1.0.4"
}
Test image compression
% epub-image-helper | jq -r '.version'
1.0.4
% python3 -c 'from epub_image_helper.testImageCompression import testImageCompression; testImageCompression("/tmp/test-images")'
000.png
plan: png, 100: rawSize: 720749, newSize: 720749
plan: png, 95: rawSize: 720749, newSize: 923203
plan: png, 90: rawSize: 720749, newSize: 923203
plan: png, 85: rawSize: 720749, newSize: 923203
plan: jpg, 100: rawSize: 720749, newSize: 3012792
plan: jpg, 95: rawSize: 720749, newSize: 2023737
plan: jpg, 90: rawSize: 720749, newSize: 1557584
plan: jpg, 85: rawSize: 720749, newSize: 1310936
...
Batch processing Usage
% epub-image-helper | jq -r '.version'
1.0.4
% tree example
example
├── 01-batch-image-to-epub
│ ├── image2epub.py
│ └── input.json
└── 02-batch-pdf-to-epub
├── input.json
└── pdf2epub.py
3 directories, 4 files
Pack your NAS photo albums
% cd example/01-batch-image-to-epub
% tree .
.
├── epub
├── image2epub.py
├── input.json
└── storage
└── url
├── 001
│ ├── 01.jpg
│ ├── 02.jpg
│ └── 03.jpg
└── 002
├── 01.jpg
├── 02.jpg
├── 03.jpg
├── 04.jpg
└── 05.jpg
6 directories, 10 files
% cat input.json
[
{
"name": "MyPhotosA",
"author": ["Author"],
"books": [
"https://localhost/001/A",
"https://localhost/002/B",
"https://localhost/003/C"
]
},
{
"name": "MyPhotosB",
"author": ["Author"],
"books": [
"https://localhost/004/A",
"https://localhost/005/B",
"https://localhost/006/C"
]
}
]
% python3 image2epub.py
...
% tree epub
epub
└── MyPhotosA
├── MyPhotosA01.epub
└── MyPhotosA02.epub
2 directories, 2 files
Usage
% pip install epub-image-helper
% epub-image-helper
{
"status": false,
"input": {
"output": "/tmp/test.epub",
"bookConfig": "{}",
"bookCover": "",
"bookId": "20a3f61e-8c83-4fca-9846-afd5ffbf108a",
"bookTitle": "Unknown",
"bookAuthor": "Unknown",
"epubcheck": false,
"imageDir": [],
"pickFirstImageToBeBookCover": false,
"debug": false,
"bookTableOfContent": [],
"imageFormatConversionTable": {}
},
"output": {
"path": null,
"size": 0,
"sizeReadable": null,
"imageCount": 0,
"timeCost": [
5.9604644775390625e-06
]
},
"error": [
"If both 'imageDir' and 'bookTableOfContent' are empty, please set at least one of them."
],
"version": "1.0.0"
}
% epub-image-helper -h
usage: epub-image-helper [-h] [--output OUTPUT] [--bookConfig BOOKCONFIG] [--bookCover BOOKCOVER] [--bookTitle BOOKTITLE]
[--bookId BOOKID] [--bookAuthor BOOKAUTHOR] [--pickFirstImageToBeBookCover] [--debug]
[--epubcheck]
[imageDir ...]
positional arguments:
imageDir the directory where the image file is located
options:
-h, --help show this help message and exit
--output OUTPUT output epub path
--bookConfig BOOKCONFIG
a JSON config for EPUB builder. '@-' will read from stdin
--bookCover BOOKCOVER
set a cover image for EPUB
--bookTitle BOOKTITLE
set book title
--bookId BOOKID set book uuid info
--bookAuthor BOOKAUTHOR
set book author info
--pickFirstImageToBeBookCover
Select the first image as the book cover when the 'bookCover' parameter is not specified
--debug show bookConfig only
--epubcheck test output epub format via epubcheck command
1. From an image folder to an EPUB book
% tree 01-image-folder
01-image-folder
├── 01.jpg
├── 02.jpg
└── 03.jpg
1 directory, 3 files
% epub-image-helper exmaple/01-image-folder
{
"status": true,
"input": {
"output": "/tmp/test.epub",
"bookConfig": "{}",
"bookCover": "",
"bookId": "b717c302-b724-40aa-a9bf-dbe885b51bfb",
"bookTitle": "Unknown",
"bookAuthor": "Unknown",
"epubcheck": false,
"imageDir": [
"exmaple/01-image-folder"
],
"pickFirstImageToBeBookCover": false,
"debug": false,
"bookTableOfContent": [
{
"type": "imageDir",
"name": "01-image-folder",
"imageDir": "exmaple/01-image-folder"
}
],
"imageFormatConversionTable": {}
},
"output": {
"path": "/tmp/test.epub",
"size": 361025,
"sizeReadable": "352.56 KB",
"imageCount": 0,
"timeCost": [
5.221366882324219e-05,
5.1021575927734375e-05,
0.012903928756713867
]
},
"error": [],
"version": "1.0.0"
}
% unzip -l /tmp/test.epub
Archive: /tmp/test.epub
Length Date Time Name
--------- ---------- ----- ----
20 12-17-2023 10:32 mimetype
251 12-17-2023 10:32 META-INF/container.xml
1802 12-17-2023 10:32 EPUB/content.opf
55 12-17-2023 10:32 EPUB/default.css
128903 12-17-2023 10:32 EPUB/img-1-000002.jpg
619 12-17-2023 10:32 EPUB/xhtml-1-000003.xhtml
88590 12-17-2023 10:32 EPUB/img-1-000004.jpg
619 12-17-2023 10:32 EPUB/xhtml-1-000005.xhtml
142203 12-17-2023 10:32 EPUB/img-1-000006.jpg
620 12-17-2023 10:32 EPUB/xhtml-1-000007.xhtml
411 12-17-2023 10:32 EPUB/toc.ncx
333 12-17-2023 10:32 EPUB/nav.xhtml
--------- -------
364426 12 files
2. From multiple image folders to an EPUB book
% tree 02-multiple-image-folders
02-multiple-image-folders
├── first
│ ├── 01.jpg
│ ├── 02.jpg
│ └── 03.jpg
└── second
├── 01.jpg
├── 02.jpg
├── 03.jpg
├── 04.jpg
└── 05.jpg
3 directories, 8 files
% epub-image-helper 02-multiple-image-folders
{
"status": true,
"input": {
"output": "/tmp/test.epub",
"bookConfig": "{}",
"bookCover": "",
"bookId": "011af0b8-0340-4f5d-b22a-10dbc0a52eea",
"bookTitle": "Unknown",
"bookAuthor": "Unknown",
"epubcheck": false,
"imageDir": [
"exmaple/02-multiple-image-folders"
],
"pickFirstImageToBeBookCover": false,
"debug": false,
"bookTableOfContent": [
{
"type": "imageDir",
"name": "02-multiple-image-folders",
"imageDir": "exmaple/02-multiple-image-folders"
}
],
"imageFormatConversionTable": {}
},
"output": {
"path": "/tmp/test.epub",
"size": 26444959,
"sizeReadable": "25.22 MB",
"imageCount": 0,
"timeCost": [
4.696846008300781e-05,
0.00010395050048828125,
0.5822200775146484
]
},
"error": [],
"version": "1.0.0"
}
% unzip -l /tmp/test.epub
Archive: /tmp/test.epub
Length Date Time Name
--------- ---------- ----- ----
20 12-17-2023 10:57 mimetype
251 12-17-2023 10:57 META-INF/container.xml
2807 12-17-2023 10:57 EPUB/content.opf
55 12-17-2023 10:57 EPUB/default.css
128903 12-17-2023 10:57 EPUB/img-1-000002.jpg
629 12-17-2023 10:57 EPUB/xhtml-1-000003.xhtml
88590 12-17-2023 10:57 EPUB/img-1-000004.jpg
629 12-17-2023 10:57 EPUB/xhtml-1-000005.xhtml
142203 12-17-2023 10:57 EPUB/img-1-000006.jpg
629 12-17-2023 10:57 EPUB/xhtml-1-000007.xhtml
11474510 12-17-2023 10:57 EPUB/img-1-000008.jpg
631 12-17-2023 10:57 EPUB/xhtml-1-000009.xhtml
6709355 12-17-2023 10:57 EPUB/img-1-000010.jpg
631 12-17-2023 10:57 EPUB/xhtml-1-000011.xhtml
2372710 12-17-2023 10:57 EPUB/img-1-000012.jpg
631 12-17-2023 10:57 EPUB/xhtml-1-000013.xhtml
5484157 12-17-2023 10:57 EPUB/img-1-000014.jpg
631 12-17-2023 10:57 EPUB/xhtml-1-000015.xhtml
114318 12-17-2023 10:57 EPUB/img-1-000016.jpg
630 12-17-2023 10:57 EPUB/xhtml-1-000017.xhtml
411 12-17-2023 10:57 EPUB/toc.ncx
333 12-17-2023 10:57 EPUB/nav.xhtml
--------- -------
26523664 22 files
% epub-image-helper 02-multiple-image-folders/first 02-multiple-image-folders/second
{
"status": true,
"input": {
"output": "/tmp/test.epub",
"bookConfig": "{}",
"bookCover": "",
"bookId": "5026a99b-257b-4c1d-bb51-d4c2fc6e3610",
"bookTitle": "Unknown",
"bookAuthor": "Unknown",
"epubcheck": false,
"imageDir": [
"exmaple/02-multiple-image-folders/first",
"exmaple/02-multiple-image-folders/second"
],
"pickFirstImageToBeBookCover": false,
"debug": false,
"bookTableOfContent": [
{
"type": "imageDir",
"name": "first",
"imageDir": "exmaple/02-multiple-image-folders/first"
},
{
"type": "imageDir",
"name": "second",
"imageDir": "exmaple/02-multiple-image-folders/second"
}
],
"imageFormatConversionTable": {}
},
"output": {
"path": "/tmp/test.epub",
"size": 26444875,
"sizeReadable": "25.22 MB",
"imageCount": 0,
"timeCost": [
5.984306335449219e-05,
7.414817810058594e-05,
0.5851681232452393
]
},
"error": [],
"version": "1.0.0"
}
% unzip -l /tmp/test.epub
Archive: /tmp/test.epub
Length Date Time Name
--------- ---------- ----- ----
20 12-17-2023 11:01 mimetype
251 12-17-2023 11:01 META-INF/container.xml
2807 12-17-2023 11:01 EPUB/content.opf
55 12-17-2023 11:01 EPUB/default.css
128903 12-17-2023 11:01 EPUB/img-1-000002.jpg
609 12-17-2023 11:01 EPUB/xhtml-1-000003.xhtml
88590 12-17-2023 11:01 EPUB/img-1-000004.jpg
609 12-17-2023 11:01 EPUB/xhtml-1-000005.xhtml
142203 12-17-2023 11:01 EPUB/img-1-000006.jpg
610 12-17-2023 11:01 EPUB/xhtml-1-000007.xhtml
11474510 12-17-2023 11:01 EPUB/img-2-000008.jpg
612 12-17-2023 11:01 EPUB/xhtml-2-000009.xhtml
6709355 12-17-2023 11:01 EPUB/img-2-000010.jpg
612 12-17-2023 11:01 EPUB/xhtml-2-000011.xhtml
2372710 12-17-2023 11:01 EPUB/img-2-000012.jpg
612 12-17-2023 11:01 EPUB/xhtml-2-000013.xhtml
5484157 12-17-2023 11:01 EPUB/img-2-000014.jpg
612 12-17-2023 11:01 EPUB/xhtml-2-000015.xhtml
114318 12-17-2023 11:01 EPUB/img-2-000016.jpg
611 12-17-2023 11:01 EPUB/xhtml-2-000017.xhtml
411 12-17-2023 11:01 EPUB/toc.ncx
333 12-17-2023 11:01 EPUB/nav.xhtml
--------- -------
26523510 22 files
2. Convert all images from a PDF file to an EPUB file.
% pdfinfo /tmp/test.pdf | grep Pages
Pages: 3
% echo '{"bookTableOfContent": [ { "type": "imagePdf", "name": "Test", "imagePdf": "/tmp/test.pdf", "workDir": "/tmp/workDir-test.pdf", "imagePdfSaveFormat": "jpg" , "imagePdfSaveQuality": 100 } ]}' | epub-image-helper --bookConfig @-
{
"status": false,
"input": {
"output": "/tmp/test.epub",
"bookConfig": "@-",
"bookCover": "",
"bookId": "438e9899-eafc-42ef-bc21-c0134c4f82f4",
"bookTitle": "Unknown",
"bookAuthor": "Unknown",
"epubcheck": false,
"imageDir": [],
"pickFirstImageToBeBookCover": false,
"debug": false,
"bookTableOfContent": [
{
"type": "imagePdf",
"name": "Test",
"imagePdf": "/tmp/test.pdf",
"workDir": "/tmp/workDir-test.pdf",
"imagePdfSaveFormat": "jpg",
"imagePdfSaveQuality": 100
}
],
"imageFormatConversionTable": {},
"stdin": "{\"bookTableOfContent\": [ { \"type\": \"imagePdf\", \"name\": \"Test\", \"imagePdf\": \"/tmp/test.pdf\", \"workDir\": \"/tmp/workDir-test.pdf\", \"imagePdfSaveFormat\": \"jpg\" , \"imagePdfSaveQuality\": 100 } ]}\n"
},
"output": {
"path": null,
"size": 0,
"sizeReadable": null,
"imageCount": 0,
"timeCost": [
2.9087066650390625e-05,
3.0279159545898438e-05
]
},
"error": [
{
"status": false,
"error": [
"type=\"imagePdf\" error, \"workDir\" not exists: index=0, item={'type': 'imagePdf', 'name': 'Test', 'imagePdf': '/tmp/test.pdf', 'workDir': '/tmp/workDir-test.pdf', 'imagePdfSaveFormat': 'jpg', 'imagePdfSaveQuality': 100}"
],
"input": [
{
"type": "imagePdf",
"name": "Test",
"imagePdf": "/tmp/test.pdf",
"workDir": "/tmp/workDir-test.pdf",
"imagePdfSaveFormat": "jpg",
"imagePdfSaveQuality": 100
}
],
"output": [],
"totalImage": 0,
"timeCost": []
}
],
"version": "1.0.0"
}
% mkdir /tmp/workDir-test.pdf
% echo '{"bookTableOfContent": [ { "type": "imagePdf", "name": "Test", "imagePdf": "/tmp/test.pdf", "workDir": "/tmp/workDir-test.pdf", "imagePdfSaveFormat": "jpg" , "imagePdfSaveQuality": 100 } ]}' | epub-image-helper --bookConfig @-
{
"status": true,
"input": {
"output": "/tmp/test.epub",
"bookConfig": "@-",
"bookCover": "",
"bookId": "1e788bee-4f66-49f5-bce3-c412a7a4a348",
"bookTitle": "Unknown",
"bookAuthor": "Unknown",
"epubcheck": false,
"imageDir": [],
"pickFirstImageToBeBookCover": false,
"debug": false,
"bookTableOfContent": [
{
"type": "imagePdf",
"name": "Test",
"imagePdf": "/tmp/test.pdf",
"workDir": "/tmp/workDir-test.pdf",
"imagePdfSaveFormat": "jpg",
"imagePdfSaveQuality": 100
}
],
"imageFormatConversionTable": {},
"stdin": "{\"bookTableOfContent\": [ { \"type\": \"imagePdf\", \"name\": \"Test\", \"imagePdf\": \"/tmp/test.pdf\", \"workDir\": \"/tmp/workDir-test.pdf\", \"imagePdfSaveFormat\": \"jpg\" , \"imagePdfSaveQuality\": 100 } ]}\n"
},
"output": {
"path": "/tmp/test.epub",
"size": 361006,
"sizeReadable": "352.54 KB",
"imageCount": 0,
"timeCost": [
3.0994415283203125e-05,
0.035225868225097656,
0.013682126998901367
]
},
"error": [],
"version": "1.0.0"
}
% unzip -l /tmp/test.epub
Archive: /tmp/test.epub
Length Date Time Name
--------- ---------- ----- ----
20 12-17-2023 13:37 mimetype
251 12-17-2023 13:37 META-INF/container.xml
1802 12-17-2023 13:37 EPUB/content.opf
55 12-17-2023 13:37 EPUB/default.css
128903 12-17-2023 13:37 EPUB/img-1-000002.jpg
608 12-17-2023 13:37 EPUB/xhtml-1-000003.xhtml
88590 12-17-2023 13:37 EPUB/img-1-000004.jpg
608 12-17-2023 13:37 EPUB/xhtml-1-000005.xhtml
142203 12-17-2023 13:37 EPUB/img-1-000006.jpg
609 12-17-2023 13:37 EPUB/xhtml-1-000007.xhtml
411 12-17-2023 13:37 EPUB/toc.ncx
333 12-17-2023 13:37 EPUB/nav.xhtml
--------- -------
364393 12 files
1 maintainer
Metadata
1 maintainer
Release files for epub-image-helper 1.0.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| epub_image_helper-1.0.7.tar.gz | 18.8 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| epub_image_helper-1.0.7-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 35.1 kB
Release files / epub_image_helper-1.0.7.tar.gz
| Download URL | epub_image_helper-1.0.7.tar.gz |
|---|---|
| Size | 18.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b7b9a66e6b8a54b3139d9c46c4d7096428242d9bb9d46396fb2d9e9b08816058
|
|
BLAKE2b-256 checksum How to use checksums |
80f8e403c0a658b0c810dcab158709616cdd34d7082f750d82e9f6798aa3df4b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 4, 2025.
Transparency logRelease files / epub_image_helper-1.0.7-py3-none-any.whl
| Download URL | epub_image_helper-1.0.7-py3-none-any.whl |
|---|---|
| Size | 16.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a6d735b95d82c7c452be5376c4bd189e17f4607ed0fdd29cdab839d0010ad40b
|
|
BLAKE2b-256 checksum How to use checksums |
99be1b7bc2c77a7889fc316937be2a8c47d2623c8271750e9e41ef8201f4c6b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 4, 2025.
Transparency logSecurity for epub-image-helper 1.0.7
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.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for epub_image_helper-1.0.7.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 4, 2025.
Transparency logA 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.
