Skip to content
BranchesTags

Repository files navigation

gs-batch-pdf

A command-line tool for batch processing PDF files using Ghostscript with parallel execution. Process multiple PDFs simultaneously while applying compression, PDF/A conversion, or custom Ghostscript options.

Features

  • Parallel Processing: Multi-threaded execution for faster batch operations
  • Compression: Multiple quality levels (/screen, /ebook, /printer, /prepress, /default)
  • PDF/A Conversion: Support for PDF/A-1, PDF/A-2, and PDF/A-3 standards1
  • Recursive Search: Process entire directory trees with the -r flag
  • Smart File Management: Keep smaller files automatically or always keep new versions
  • Error Handling: Configurable error behavior (prompt, skip, or abort)
  • Custom Ghostscript Options: Full access to Ghostscript's command-line options
  • Progress Tracking: Real-time progress bars for each file being processed
  • Flexible Output: Add prefixes/suffixes to output filenames, organize into folders
  • Cross-platform: Windows, Linux, and macOS support

Installation

Prerequisites

  1. Python 3.12+: Required to run the tool
  2. Ghostscript: Required for PDF processing. Install from ghostscript.com

Install gs-batch-pdf

Using pipx (recommended)2:

pipx install gs-batch-pdf

Or using pip:

pip install gs-batch-pdf

Usage

The tool is available via two commands: gs_batch or its shorter alias gsb.

Basic Syntax

gsb [OPTIONS] FILES_OR_DIRECTORIES...

or (my preference):

gsb FILES_OR_DIRECTORIES... [OPTIONS]

Quick Start

# Compress all PDFs in current directory (default: /ebook quality)
gsb . --compress
# Compress PDFs recursively in a directory tree
gsb ./docs/ -r --compress
# Convert a single PDF to PDF/A-2
gsb file.pdf --pdfa
# Compress and convert to PDF/A with custom output
gsb *.pdf --compress --pdfa --prefix "processed_"

Note: When using options that can take optional values (like --compress or --pdfa), place them after the file arguments for simplest usage, or see Using Options with File Arguments for alternatives.

Options

Processing Options

  • --compress [LEVEL]: Compress PDFs with quality level

    • Levels: /screen, /ebook (default), /printer, /prepress, /default
    • Use without value for /ebook quality

  • --pdfa [VERSION]: Convert to PDF/A format

    • Versions: 1 (PDF/A-1), 2 (PDF/A-2, default), 3 (PDF/A-3)
    • Use without value for PDF/A-2

  • --options TEXT: Pass arbitrary Ghostscript options

    • Example: --options "-dColorImageResolution=100 -dCompatibilityLevel=1.4"

File Management Options

  • --prefix TEXT: Add prefix to output filenames

    • Can include path: --prefix "output/" creates files in output directory
    • Relative paths calculated from input file location, not current directory

  • --suffix TEXT: Add suffix before file extension

    • Example: --suffix "_compressed" → file_compressed.pdf

  • --keep_smaller / --keep_new: Choose which file to keep (default: --keep_smaller)

    • --keep_smaller: Keep whichever file is smaller (original or processed)
    • --keep_new: Always keep the processed file
    • Note: PDF/A conversion always keeps new file

  • -f, --force: Allow overwriting original files without confirmation

    • Required when no prefix specified and files would be overwritten

Search Options

  • --filter TEXT: Filter files by extension (default: pdf)

    • Supports comma-separated list: --filter pdf,png

  • -r, --recursive: Search directories recursively

    • Without this flag, only processes files in top-level directories

Error Handling Options

  • --on-error [MODE]: Control behavior when file processing errors occur
    • prompt (default): Interactively ask user whether to retry, skip, or abort
    • skip: Automatically skip failed files and continue processing
    • abort: Stop processing immediately on first error

Other Options

  • --timeout INTEGER: Maximum processing time per file in seconds (default: 300)
    • Set to 0 to disable timeout protection
    • Prevents indefinite hangs on problematic PDFs
  • --open_path / --no_open_path: Open output location in file manager (default: enabled)
  • -v, --verbose: Show detailed Ghostscript command output
  • --version: Show version information
  • --help: Display help message

Using Options with File Arguments

When using options that accept optional values (--compress, --pdfa), you have three approaches:

1. Place options after file arguments (recommended):

gsb *.pdf --compress
gsb * --compress --pdfa

2. Provide explicit values:

gsb --compress /ebook *.pdf
gsb --pdfa 2 *.pdf

3. Use -- separator:

gsb --compress -- *.pdf
gsb --pdfa -- *.pdf

Examples

Basic Compression

Compress multiple PDFs with /ebook quality (in-place)3:

gsb file1.pdf file2.pdf file3.pdf --compress

Compress all PDFs in a directory:

gsb . --compress

Compress with specific quality level:

gsb document.pdf --compress /screen
# or with explicit value before files:
gsb --compress /screen *.pdf

PDF/A Conversion

Convert to PDF/A-2 (default):

gsb report.pdf --pdfa

Convert to specific PDF/A version:

gsb document.pdf --pdfa 3
# or with explicit value before files:
gsb --pdfa 3 *.pdf

Compress and convert to PDF/A:

gsb invoice.pdf --compress --pdfa

Recursive Processing

Process entire directory tree:

# Find and compress all PDFs in current directory and subdirectories
gsb . -r --compress
# Process specific directory recursively
gsb ./documents/ -r --compress --pdfa

Process with force (no confirmation):

gsb . -r --compress --pdfa --force

Custom Output Organization

Add prefix to create organized output:

# Add prefix to filenames
gsb *.pdf --prefix "compressed_" --compress
# Create files in subdirectory
gsb *.pdf --prefix "output/" --compress
# Add both prefix and suffix
gsb *.pdf --prefix "processed_" --suffix "_v1" --compress

Keep new files regardless of size:

gsb document.pdf --compress --keep_new

Advanced Ghostscript Options

Apply custom Ghostscript settings:

gsb file.pdf --options "-dCompatibilityLevel=1.4 -dColorImageResolution=72"

Combine compression with custom options:

gsb report.pdf --compress /printer --options "-dCompatibilityLevel=1.7"

Error Handling

Interactive error handling (default):

# Prompts user on each error to retry, skip, or abort
gsb . -r --compress

Skip failed files automatically:

# Useful for batch processing where some files may be corrupted
gsb . -r --compress --on-error skip

Abort on first error:

# Stops immediately if any file fails (useful for CI/CD)
gsb *.pdf --compress --on-error abort

Scripting and Automation

Silent processing for scripts:

gsb *.pdf --compress --force --no_open_path

Automated batch with error skipping:

# Best for unattended processing
gsb . -r --compress --force --no_open_path --on-error skip

Verbose output for debugging:

gsb document.pdf -v --compress --pdfa

Process with custom timeout for large files:

# Set 10 minute timeout for very large PDFs
gsb large-document.pdf --compress --timeout 600
# Disable timeout for files that take a long time
gsb complex-document.pdf --compress --timeout 0

Output

After processing completes, gs-batch-pdf displays a detailed summary table:

Processing 3 file(s):
1) document1.pdf
2) document2.pdf
3) document3.pdf
[Progress bars shown during processing...]
# | Original | New | Ratio | Keeping | Filename
1 | 1,234 KB | 856 KB | 69.400% | new | /path/to/document1.pdf
2 | 789 KB | 654 KB | 82.900% | new | /path/to/document2.pdf
3 | 456 KB | 512 KB | 112.300% | original | /path/to/document3.pdf
Total time: 12.34 seconds

The summary shows:

  • Original: Size of the input file
  • New: Size of the processed file
  • Ratio: New size as percentage of original (lower is better for compression)
  • Keeping: Which version was kept based on --keep_smaller or --keep_new
  • Filename: Absolute path to the output file

By default, the tool opens the output location in your file manager after processing (disable with --no_open_path).

Troubleshooting

Ghostscript Not Found

If you get an error about Ghostscript not being found:

  1. Verify Ghostscript is installed: gs --version (Linux/macOS) or gswin64c --version (Windows)
  2. Ensure Ghostscript is in your system PATH
  3. On Windows, you may need to restart your terminal after installation

PDF/A Conversion Issues

For PDF/A-2 and PDF/A-3 conversion, ensure you're using Ghostscript 10.04.0 or higher:

gs --version

Permission Errors

If you encounter permission errors when processing files:

  • Use --prefix to write to a different directory
  • Check file permissions on both input and output locations
  • On Windows, ensure files aren't open in another program

Timeout Issues

If processing is hanging or taking too long:

  • The default timeout is 5 minutes (300 seconds) per file
  • For large or complex PDFs, increase the timeout: --timeout 600 (10 minutes)
  • To disable timeout protection: --timeout 0
  • Some corrupted PDFs may cause Ghostscript to hang indefinitely - timeout protection will terminate these processes

Contributing

Contributions are welcome! Please feel free to:

  • Report bugs or request features via GitHub Issues
  • Submit Pull Requests for improvements
  • Share feedback and suggestions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

This tool is built on top of Ghostscript, released under the GNU Affero General Public License (AGPL). gs-batch-pdf is a CLI wrapper and is independently licensed under MIT.

Footnotes

  1. Requires Ghostscript version 10.04.0 or higher for correct PDF/A-2 and PDF/A-3 conversion. ↩

  2. pipx installs the package in an isolated virtual environment while making commands globally available. ↩

  3. When no --prefix is provided and files would be overwritten, you'll be prompted for confirmation unless --force is used. ↩

About

No description, website, or topics provided.

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

5 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
GitHub - kompre/gs-batch · GitHub
Skip to content
BranchesTags
Repository files navigation
gs-batch-pdf
A command-line tool for batch processing PDF files using Ghostscript with parallel execution. Process multiple PDFs simultaneously while applying compression, PDF/A conversion, or custom Ghostscript options.
Features
  • Parallel Processing: Multi-threaded execution for faster batch operations
  • Compression: Multiple quality levels (/screen, /ebook, /printer, /prepress, /default)
  • PDF/A Conversion: Support for PDF/A-1, PDF/A-2, and PDF/A-3 standards1
  • Recursive Search: Process entire directory trees with the -r flag
  • Smart File Management: Keep smaller files automatically or always keep new versions
  • Error Handling: Configurable error behavior (prompt, skip, or abort)
  • Custom Ghostscript Options: Full access to Ghostscript's command-line options
  • Progress Tracking: Real-time progress bars for each file being processed
  • Flexible Output: Add prefixes/suffixes to output filenames, organize into folders
  • Cross-platform: Windows, Linux, and macOS support
Installation
Prerequisites
  1. Python 3.12+: Required to run the tool
  2. Ghostscript: Required for PDF processing. Install from ghostscript.com
Install gs-batch-pdf
Using pipx (recommended)2:
pipx install gs-batch-pdf
Or using pip:
pip install gs-batch-pdf
Usage
The tool is available via two commands: gs_batch or its shorter alias gsb.
Basic Syntax
gsb [OPTIONS] FILES_OR_DIRECTORIES...
or (my preference):
gsb FILES_OR_DIRECTORIES... [OPTIONS]
Quick Start
# Compress all PDFs in current directory (default: /ebook quality)
gsb . --compress
# Compress PDFs recursively in a directory tree
gsb ./docs/ -r --compress
# Convert a single PDF to PDF/A-2
gsb file.pdf --pdfa
# Compress and convert to PDF/A with custom output
gsb *.pdf --compress --pdfa --prefix "processed_"
Note: When using options that can take optional values (like --compress or --pdfa), place them after the file arguments for simplest usage, or see Using Options with File Arguments for alternatives.
Options
Processing Options
  • --compress [LEVEL]: Compress PDFs with quality level
    • Levels: /screen, /ebook (default), /printer, /prepress, /default
    • Use without value for /ebook quality
  • --pdfa [VERSION]: Convert to PDF/A format
    • Versions: 1 (PDF/A-1), 2 (PDF/A-2, default), 3 (PDF/A-3)
    • Use without value for PDF/A-2
  • --options TEXT: Pass arbitrary Ghostscript options
    • Example: --options "-dColorImageResolution=100 -dCompatibilityLevel=1.4"
File Management Options
  • --prefix TEXT: Add prefix to output filenames
    • Can include path: --prefix "output/" creates files in output directory
    • Relative paths calculated from input file location, not current directory
  • --suffix TEXT: Add suffix before file extension
    • Example: --suffix "_compressed" → file_compressed.pdf
  • --keep_smaller / --keep_new: Choose which file to keep (default: --keep_smaller)
    • --keep_smaller: Keep whichever file is smaller (original or processed)
    • --keep_new: Always keep the processed file
    • Note: PDF/A conversion always keeps new file
  • -f, --force: Allow overwriting original files without confirmation
    • Required when no prefix specified and files would be overwritten
Search Options
  • --filter TEXT: Filter files by extension (default: pdf)
    • Supports comma-separated list: --filter pdf,png
  • -r, --recursive: Search directories recursively
    • Without this flag, only processes files in top-level directories
Error Handling Options
  • --on-error [MODE]: Control behavior when file processing errors occur

    • prompt (default): Interactively ask user whether to retry, skip, or abort
    • skip: Automatically skip failed files and continue processing
    • abort: Stop processing immediately on first error
Other Options
  • --timeout INTEGER: Maximum processing time per file in seconds (default: 300)

    • Set to 0 to disable timeout protection
    • Prevents indefinite hangs on problematic PDFs
  • --open_path / --no_open_path: Open output location in file manager (default: enabled)
  • -v, --verbose: Show detailed Ghostscript command output
  • --version: Show version information
  • --help: Display help message
Using Options with File Arguments
When using options that accept optional values (--compress, --pdfa), you have three approaches:
1. Place options after file arguments (recommended):
gsb *.pdf --compress
gsb * --compress --pdfa
2. Provide explicit values:
gsb --compress /ebook *.pdf
gsb --pdfa 2 *.pdf
3. Use -- separator:
gsb --compress -- *.pdf
gsb --pdfa -- *.pdf
Examples
Basic Compression
Compress multiple PDFs with /ebook quality (in-place)3:
gsb file1.pdf file2.pdf file3.pdf --compress
Compress all PDFs in a directory:
gsb . --compress
Compress with specific quality level:
gsb document.pdf --compress /screen
# or with explicit value before files:
gsb --compress /screen *.pdf
PDF/A Conversion
Convert to PDF/A-2 (default):
gsb report.pdf --pdfa
Convert to specific PDF/A version:
gsb document.pdf --pdfa 3
# or with explicit value before files:
gsb --pdfa 3 *.pdf
Compress and convert to PDF/A:
gsb invoice.pdf --compress --pdfa
Recursive Processing
Process entire directory tree:
# Find and compress all PDFs in current directory and subdirectories
gsb . -r --compress
# Process specific directory recursively
gsb ./documents/ -r --compress --pdfa
Process with force (no confirmation):
gsb . -r --compress --pdfa --force
Custom Output Organization
Add prefix to create organized output:
# Add prefix to filenames
gsb *.pdf --prefix "compressed_" --compress
# Create files in subdirectory
gsb *.pdf --prefix "output/" --compress
# Add both prefix and suffix
gsb *.pdf --prefix "processed_" --suffix "_v1" --compress
Keep new files regardless of size:
gsb document.pdf --compress --keep_new
Advanced Ghostscript Options
Apply custom Ghostscript settings:
gsb file.pdf --options "-dCompatibilityLevel=1.4 -dColorImageResolution=72"
Combine compression with custom options:
gsb report.pdf --compress /printer --options "-dCompatibilityLevel=1.7"
Error Handling
Interactive error handling (default):
# Prompts user on each error to retry, skip, or abort
gsb . -r --compress
Skip failed files automatically:
# Useful for batch processing where some files may be corrupted
gsb . -r --compress --on-error skip
Abort on first error:
# Stops immediately if any file fails (useful for CI/CD)
gsb *.pdf --compress --on-error abort
Scripting and Automation
Silent processing for scripts:
gsb *.pdf --compress --force --no_open_path
Automated batch with error skipping:
# Best for unattended processing
gsb . -r --compress --force --no_open_path --on-error skip
Verbose output for debugging:
gsb document.pdf -v --compress --pdfa
Process with custom timeout for large files:
# Set 10 minute timeout for very large PDFs
gsb large-document.pdf --compress --timeout 600
# Disable timeout for files that take a long time
gsb complex-document.pdf --compress --timeout 0
Output
After processing completes, gs-batch-pdf displays a detailed summary table:
Processing 3 file(s):
1) document1.pdf
2) document2.pdf
3) document3.pdf
[Progress bars shown during processing...]
# | Original | New | Ratio | Keeping | Filename
1 | 1,234 KB | 856 KB | 69.400% | new | /path/to/document1.pdf
2 | 789 KB | 654 KB | 82.900% | new | /path/to/document2.pdf
3 | 456 KB | 512 KB | 112.300% | original | /path/to/document3.pdf
Total time: 12.34 seconds

The summary shows:
  • Original: Size of the input file
  • New: Size of the processed file
  • Ratio: New size as percentage of original (lower is better for compression)
  • Keeping: Which version was kept based on --keep_smaller or --keep_new
  • Filename: Absolute path to the output file
By default, the tool opens the output location in your file manager after processing (disable with --no_open_path).
Troubleshooting
Ghostscript Not Found
If you get an error about Ghostscript not being found:
  1. Verify Ghostscript is installed: gs --version (Linux/macOS) or gswin64c --version (Windows)
  2. Ensure Ghostscript is in your system PATH
  3. On Windows, you may need to restart your terminal after installation
PDF/A Conversion Issues
For PDF/A-2 and PDF/A-3 conversion, ensure you're using Ghostscript 10.04.0 or higher:
gs --version
Permission Errors
If you encounter permission errors when processing files:
  • Use --prefix to write to a different directory
  • Check file permissions on both input and output locations
  • On Windows, ensure files aren't open in another program
Timeout Issues
If processing is hanging or taking too long:
  • The default timeout is 5 minutes (300 seconds) per file
  • For large or complex PDFs, increase the timeout: --timeout 600 (10 minutes)
  • To disable timeout protection: --timeout 0
  • Some corrupted PDFs may cause Ghostscript to hang indefinitely - timeout protection will terminate these processes
Contributing
Contributions are welcome! Please feel free to:
  • Report bugs or request features via GitHub Issues
  • Submit Pull Requests for improvements
  • Share feedback and suggestions
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgements
This tool is built on top of Ghostscript, released under the GNU Affero General Public License (AGPL). gs-batch-pdf is a CLI wrapper and is independently licensed under MIT.
Footnotes
  1. Requires Ghostscript version 10.04.0 or higher for correct PDF/A-2 and PDF/A-3 conversion. ↩
  2. pipx installs the package in an isolated virtual environment while making commands globally available. ↩
  3. When no --prefix is provided and files would be overwritten, you'll be prompted for confirmation unless --force is used. ↩
About
No description, website, or topics provided.
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
5 stars
Watchers
1 watching
Forks
0 forks
Report repository
Releases
Packages
Used by
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
GitHub - kompre/gs-batch · GitHub
Skip to content
BranchesTags
Repository files navigation
gs-batch-pdf
A command-line tool for batch processing PDF files using Ghostscript with parallel execution. Process multiple PDFs simultaneously while applying compression, PDF/A conversion, or custom Ghostscript options.
Features
  • Parallel Processing: Multi-threaded execution for faster batch operations
  • Compression: Multiple quality levels (/screen, /ebook, /printer, /prepress, /default)
  • PDF/A Conversion: Support for PDF/A-1, PDF/A-2, and PDF/A-3 standards1
  • Recursive Search: Process entire directory trees with the -r flag
  • Smart File Management: Keep smaller files automatically or always keep new versions
  • Error Handling: Configurable error behavior (prompt, skip, or abort)
  • Custom Ghostscript Options: Full access to Ghostscript's command-line options
  • Progress Tracking: Real-time progress bars for each file being processed
  • Flexible Output: Add prefixes/suffixes to output filenames, organize into folders
  • Cross-platform: Windows, Linux, and macOS support
Installation
Prerequisites
  1. Python 3.12+: Required to run the tool
  2. Ghostscript: Required for PDF processing. Install from ghostscript.com
Install gs-batch-pdf
Using pipx (recommended)2:
pipx install gs-batch-pdf
Or using pip:
pip install gs-batch-pdf
Usage
The tool is available via two commands: gs_batch or its shorter alias gsb.
Basic Syntax
gsb [OPTIONS] FILES_OR_DIRECTORIES...
or (my preference):
gsb FILES_OR_DIRECTORIES... [OPTIONS]
Quick Start
# Compress all PDFs in current directory (default: /ebook quality)
gsb . --compress
# Compress PDFs recursively in a directory tree
gsb ./docs/ -r --compress
# Convert a single PDF to PDF/A-2
gsb file.pdf --pdfa
# Compress and convert to PDF/A with custom output
gsb *.pdf --compress --pdfa --prefix "processed_"
Note: When using options that can take optional values (like --compress or --pdfa), place them after the file arguments for simplest usage, or see Using Options with File Arguments for alternatives.
Options
Processing Options
  • --compress [LEVEL]: Compress PDFs with quality level
    • Levels: /screen, /ebook (default), /printer, /prepress, /default
    • Use without value for /ebook quality
  • --pdfa [VERSION]: Convert to PDF/A format
    • Versions: 1 (PDF/A-1), 2 (PDF/A-2, default), 3 (PDF/A-3)
    • Use without value for PDF/A-2
  • --options TEXT: Pass arbitrary Ghostscript options
    • Example: --options "-dColorImageResolution=100 -dCompatibilityLevel=1.4"
File Management Options
  • --prefix TEXT: Add prefix to output filenames
    • Can include path: --prefix "output/" creates files in output directory
    • Relative paths calculated from input file location, not current directory
  • --suffix TEXT: Add suffix before file extension
    • Example: --suffix "_compressed" → file_compressed.pdf
  • --keep_smaller / --keep_new: Choose which file to keep (default: --keep_smaller)
    • --keep_smaller: Keep whichever file is smaller (original or processed)
    • --keep_new: Always keep the processed file
    • Note: PDF/A conversion always keeps new file
  • -f, --force: Allow overwriting original files without confirmation
    • Required when no prefix specified and files would be overwritten
Search Options
  • --filter TEXT: Filter files by extension (default: pdf)
    • Supports comma-separated list: --filter pdf,png
  • -r, --recursive: Search directories recursively
    • Without this flag, only processes files in top-level directories
Error Handling Options
  • --on-error [MODE]: Control behavior when file processing errors occur

    • prompt (default): Interactively ask user whether to retry, skip, or abort
    • skip: Automatically skip failed files and continue processing
    • abort: Stop processing immediately on first error
Other Options
  • --timeout INTEGER: Maximum processing time per file in seconds (default: 300)

    • Set to 0 to disable timeout protection
    • Prevents indefinite hangs on problematic PDFs
  • --open_path / --no_open_path: Open output location in file manager (default: enabled)
  • -v, --verbose: Show detailed Ghostscript command output
  • --version: Show version information
  • --help: Display help message
Using Options with File Arguments
When using options that accept optional values (--compress, --pdfa), you have three approaches:
1. Place options after file arguments (recommended):
gsb *.pdf --compress
gsb * --compress --pdfa
2. Provide explicit values:
gsb --compress /ebook *.pdf
gsb --pdfa 2 *.pdf
3. Use -- separator:
gsb --compress -- *.pdf
gsb --pdfa -- *.pdf
Examples
Basic Compression
Compress multiple PDFs with /ebook quality (in-place)3:
gsb file1.pdf file2.pdf file3.pdf --compress
Compress all PDFs in a directory:
gsb . --compress
Compress with specific quality level:
gsb document.pdf --compress /screen
# or with explicit value before files:
gsb --compress /screen *.pdf
PDF/A Conversion
Convert to PDF/A-2 (default):
gsb report.pdf --pdfa
Convert to specific PDF/A version:
gsb document.pdf --pdfa 3
# or with explicit value before files:
gsb --pdfa 3 *.pdf
Compress and convert to PDF/A:
gsb invoice.pdf --compress --pdfa
Recursive Processing
Process entire directory tree:
# Find and compress all PDFs in current directory and subdirectories
gsb . -r --compress
# Process specific directory recursively
gsb ./documents/ -r --compress --pdfa
Process with force (no confirmation):
gsb . -r --compress --pdfa --force
Custom Output Organization
Add prefix to create organized output:
# Add prefix to filenames
gsb *.pdf --prefix "compressed_" --compress
# Create files in subdirectory
gsb *.pdf --prefix "output/" --compress
# Add both prefix and suffix
gsb *.pdf --prefix "processed_" --suffix "_v1" --compress
Keep new files regardless of size:
gsb document.pdf --compress --keep_new
Advanced Ghostscript Options
Apply custom Ghostscript settings:
gsb file.pdf --options "-dCompatibilityLevel=1.4 -dColorImageResolution=72"
Combine compression with custom options:
gsb report.pdf --compress /printer --options "-dCompatibilityLevel=1.7"
Error Handling
Interactive error handling (default):
# Prompts user on each error to retry, skip, or abort
gsb . -r --compress
Skip failed files automatically:
# Useful for batch processing where some files may be corrupted
gsb . -r --compress --on-error skip
Abort on first error:
# Stops immediately if any file fails (useful for CI/CD)
gsb *.pdf --compress --on-error abort
Scripting and Automation
Silent processing for scripts:
gsb *.pdf --compress --force --no_open_path
Automated batch with error skipping:
# Best for unattended processing
gsb . -r --compress --force --no_open_path --on-error skip
Verbose output for debugging:
gsb document.pdf -v --compress --pdfa
Process with custom timeout for large files:
# Set 10 minute timeout for very large PDFs
gsb large-document.pdf --compress --timeout 600
# Disable timeout for files that take a long time
gsb complex-document.pdf --compress --timeout 0
Output
After processing completes, gs-batch-pdf displays a detailed summary table:
Processing 3 file(s):
1) document1.pdf
2) document2.pdf
3) document3.pdf
[Progress bars shown during processing...]
# | Original | New | Ratio | Keeping | Filename
1 | 1,234 KB | 856 KB | 69.400% | new | /path/to/document1.pdf
2 | 789 KB | 654 KB | 82.900% | new | /path/to/document2.pdf
3 | 456 KB | 512 KB | 112.300% | original | /path/to/document3.pdf
Total time: 12.34 seconds

The summary shows:
  • Original: Size of the input file
  • New: Size of the processed file
  • Ratio: New size as percentage of original (lower is better for compression)
  • Keeping: Which version was kept based on --keep_smaller or --keep_new
  • Filename: Absolute path to the output file
By default, the tool opens the output location in your file manager after processing (disable with --no_open_path).
Troubleshooting
Ghostscript Not Found
If you get an error about Ghostscript not being found:
  1. Verify Ghostscript is installed: gs --version (Linux/macOS) or gswin64c --version (Windows)
  2. Ensure Ghostscript is in your system PATH
  3. On Windows, you may need to restart your terminal after installation
PDF/A Conversion Issues
For PDF/A-2 and PDF/A-3 conversion, ensure you're using Ghostscript 10.04.0 or higher:
gs --version
Permission Errors
If you encounter permission errors when processing files:
  • Use --prefix to write to a different directory
  • Check file permissions on both input and output locations
  • On Windows, ensure files aren't open in another program
Timeout Issues
If processing is hanging or taking too long:
  • The default timeout is 5 minutes (300 seconds) per file
  • For large or complex PDFs, increase the timeout: --timeout 600 (10 minutes)
  • To disable timeout protection: --timeout 0
  • Some corrupted PDFs may cause Ghostscript to hang indefinitely - timeout protection will terminate these processes
Contributing
Contributions are welcome! Please feel free to:
  • Report bugs or request features via GitHub Issues
  • Submit Pull Requests for improvements
  • Share feedback and suggestions
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgements
This tool is built on top of Ghostscript, released under the GNU Affero General Public License (AGPL). gs-batch-pdf is a CLI wrapper and is independently licensed under MIT.
Footnotes
  1. Requires Ghostscript version 10.04.0 or higher for correct PDF/A-2 and PDF/A-3 conversion. ↩
  2. pipx installs the package in an isolated virtual environment while making commands globally available. ↩
  3. When no --prefix is provided and files would be overwritten, you'll be prompted for confirmation unless --force is used. ↩
About
No description, website, or topics provided.
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
5 stars
Watchers
1 watching
Forks
0 forks
Report repository
Releases
Packages
Used by
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
GitHub - kompre/gs-batch · GitHub
Skip to content
BranchesTags
Repository files navigation
gs-batch-pdf
A command-line tool for batch processing PDF files using Ghostscript with parallel execution. Process multiple PDFs simultaneously while applying compression, PDF/A conversion, or custom Ghostscript options.
Features
  • Parallel Processing: Multi-threaded execution for faster batch operations
  • Compression: Multiple quality levels (/screen, /ebook, /printer, /prepress, /default)
  • PDF/A Conversion: Support for PDF/A-1, PDF/A-2, and PDF/A-3 standards1
  • Recursive Search: Process entire directory trees with the -r flag
  • Smart File Management: Keep smaller files automatically or always keep new versions
  • Error Handling: Configurable error behavior (prompt, skip, or abort)
  • Custom Ghostscript Options: Full access to Ghostscript's command-line options
  • Progress Tracking: Real-time progress bars for each file being processed
  • Flexible Output: Add prefixes/suffixes to output filenames, organize into folders
  • Cross-platform: Windows, Linux, and macOS support
Installation
Prerequisites
  1. Python 3.12+: Required to run the tool
  2. Ghostscript: Required for PDF processing. Install from ghostscript.com
Install gs-batch-pdf
Using pipx (recommended)2:
pipx install gs-batch-pdf
Or using pip:
pip install gs-batch-pdf
Usage
The tool is available via two commands: gs_batch or its shorter alias gsb.
Basic Syntax
gsb [OPTIONS] FILES_OR_DIRECTORIES...
or (my preference):
gsb FILES_OR_DIRECTORIES... [OPTIONS]
Quick Start
# Compress all PDFs in current directory (default: /ebook quality)
gsb . --compress
# Compress PDFs recursively in a directory tree
gsb ./docs/ -r --compress
# Convert a single PDF to PDF/A-2
gsb file.pdf --pdfa
# Compress and convert to PDF/A with custom output
gsb *.pdf --compress --pdfa --prefix "processed_"
Note: When using options that can take optional values (like --compress or --pdfa), place them after the file arguments for simplest usage, or see Using Options with File Arguments for alternatives.
Options
Processing Options
  • --compress [LEVEL]: Compress PDFs with quality level
    • Levels: /screen, /ebook (default), /printer, /prepress, /default
    • Use without value for /ebook quality
  • --pdfa [VERSION]: Convert to PDF/A format
    • Versions: 1 (PDF/A-1), 2 (PDF/A-2, default), 3 (PDF/A-3)
    • Use without value for PDF/A-2
  • --options TEXT: Pass arbitrary Ghostscript options
    • Example: --options "-dColorImageResolution=100 -dCompatibilityLevel=1.4"
File Management Options
  • --prefix TEXT: Add prefix to output filenames
    • Can include path: --prefix "output/" creates files in output directory
    • Relative paths calculated from input file location, not current directory
  • --suffix TEXT: Add suffix before file extension
    • Example: --suffix "_compressed" → file_compressed.pdf
  • --keep_smaller / --keep_new: Choose which file to keep (default: --keep_smaller)
    • --keep_smaller: Keep whichever file is smaller (original or processed)
    • --keep_new: Always keep the processed file
    • Note: PDF/A conversion always keeps new file
  • -f, --force: Allow overwriting original files without confirmation
    • Required when no prefix specified and files would be overwritten
Search Options
  • --filter TEXT: Filter files by extension (default: pdf)
    • Supports comma-separated list: --filter pdf,png
  • -r, --recursive: Search directories recursively
    • Without this flag, only processes files in top-level directories
Error Handling Options
  • --on-error [MODE]: Control behavior when file processing errors occur

    • prompt (default): Interactively ask user whether to retry, skip, or abort
    • skip: Automatically skip failed files and continue processing
    • abort: Stop processing immediately on first error
Other Options
  • --timeout INTEGER: Maximum processing time per file in seconds (default: 300)

    • Set to 0 to disable timeout protection
    • Prevents indefinite hangs on problematic PDFs
  • --open_path / --no_open_path: Open output location in file manager (default: enabled)
  • -v, --verbose: Show detailed Ghostscript command output
  • --version: Show version information
  • --help: Display help message
Using Options with File Arguments
When using options that accept optional values (--compress, --pdfa), you have three approaches:
1. Place options after file arguments (recommended):
gsb *.pdf --compress
gsb * --compress --pdfa
2. Provide explicit values:
gsb --compress /ebook *.pdf
gsb --pdfa 2 *.pdf
3. Use -- separator:
gsb --compress -- *.pdf
gsb --pdfa -- *.pdf
Examples
Basic Compression
Compress multiple PDFs with /ebook quality (in-place)3:
gsb file1.pdf file2.pdf file3.pdf --compress
Compress all PDFs in a directory:
gsb . --compress
Compress with specific quality level:
gsb document.pdf --compress /screen
# or with explicit value before files:
gsb --compress /screen *.pdf
PDF/A Conversion
Convert to PDF/A-2 (default):
gsb report.pdf --pdfa
Convert to specific PDF/A version:
gsb document.pdf --pdfa 3
# or with explicit value before files:
gsb --pdfa 3 *.pdf
Compress and convert to PDF/A:
gsb invoice.pdf --compress --pdfa
Recursive Processing
Process entire directory tree:
# Find and compress all PDFs in current directory and subdirectories
gsb . -r --compress
# Process specific directory recursively
gsb ./documents/ -r --compress --pdfa
Process with force (no confirmation):
gsb . -r --compress --pdfa --force
Custom Output Organization
Add prefix to create organized output:
# Add prefix to filenames
gsb *.pdf --prefix "compressed_" --compress
# Create files in subdirectory
gsb *.pdf --prefix "output/" --compress
# Add both prefix and suffix
gsb *.pdf --prefix "processed_" --suffix "_v1" --compress
Keep new files regardless of size:
gsb document.pdf --compress --keep_new
Advanced Ghostscript Options
Apply custom Ghostscript settings:
gsb file.pdf --options "-dCompatibilityLevel=1.4 -dColorImageResolution=72"
Combine compression with custom options:
gsb report.pdf --compress /printer --options "-dCompatibilityLevel=1.7"
Error Handling
Interactive error handling (default):
# Prompts user on each error to retry, skip, or abort
gsb . -r --compress
Skip failed files automatically:
# Useful for batch processing where some files may be corrupted
gsb . -r --compress --on-error skip
Abort on first error:
# Stops immediately if any file fails (useful for CI/CD)
gsb *.pdf --compress --on-error abort
Scripting and Automation
Silent processing for scripts:
gsb *.pdf --compress --force --no_open_path
Automated batch with error skipping:
# Best for unattended processing
gsb . -r --compress --force --no_open_path --on-error skip
Verbose output for debugging:
gsb document.pdf -v --compress --pdfa
Process with custom timeout for large files:
# Set 10 minute timeout for very large PDFs
gsb large-document.pdf --compress --timeout 600
# Disable timeout for files that take a long time
gsb complex-document.pdf --compress --timeout 0
Output
After processing completes, gs-batch-pdf displays a detailed summary table:
Processing 3 file(s):
1) document1.pdf
2) document2.pdf
3) document3.pdf
[Progress bars shown during processing...]
# | Original | New | Ratio | Keeping | Filename
1 | 1,234 KB | 856 KB | 69.400% | new | /path/to/document1.pdf
2 | 789 KB | 654 KB | 82.900% | new | /path/to/document2.pdf
3 | 456 KB | 512 KB | 112.300% | original | /path/to/document3.pdf
Total time: 12.34 seconds

The summary shows:
  • Original: Size of the input file
  • New: Size of the processed file
  • Ratio: New size as percentage of original (lower is better for compression)
  • Keeping: Which version was kept based on --keep_smaller or --keep_new
  • Filename: Absolute path to the output file
By default, the tool opens the output location in your file manager after processing (disable with --no_open_path).
Troubleshooting
Ghostscript Not Found
If you get an error about Ghostscript not being found:
  1. Verify Ghostscript is installed: gs --version (Linux/macOS) or gswin64c --version (Windows)
  2. Ensure Ghostscript is in your system PATH
  3. On Windows, you may need to restart your terminal after installation
PDF/A Conversion Issues
For PDF/A-2 and PDF/A-3 conversion, ensure you're using Ghostscript 10.04.0 or higher:
gs --version
Permission Errors
If you encounter permission errors when processing files:
  • Use --prefix to write to a different directory
  • Check file permissions on both input and output locations
  • On Windows, ensure files aren't open in another program
Timeout Issues
If processing is hanging or taking too long:
  • The default timeout is 5 minutes (300 seconds) per file
  • For large or complex PDFs, increase the timeout: --timeout 600 (10 minutes)
  • To disable timeout protection: --timeout 0
  • Some corrupted PDFs may cause Ghostscript to hang indefinitely - timeout protection will terminate these processes
Contributing
Contributions are welcome! Please feel free to:
  • Report bugs or request features via GitHub Issues
  • Submit Pull Requests for improvements
  • Share feedback and suggestions
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgements
This tool is built on top of Ghostscript, released under the GNU Affero General Public License (AGPL). gs-batch-pdf is a CLI wrapper and is independently licensed under MIT.
Footnotes
  1. Requires Ghostscript version 10.04.0 or higher for correct PDF/A-2 and PDF/A-3 conversion. ↩
  2. pipx installs the package in an isolated virtual environment while making commands globally available. ↩
  3. When no --prefix is provided and files would be overwritten, you'll be prompted for confirmation unless --force is used. ↩
About
No description, website, or topics provided.
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
5 stars
Watchers
1 watching
Forks
0 forks
Report repository
Releases
Packages
Used by
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
GitHub - kompre/gs-batch · GitHub
Skip to content
BranchesTags
Repository files navigation
gs-batch-pdf
A command-line tool for batch processing PDF files using Ghostscript with parallel execution. Process multiple PDFs simultaneously while applying compression, PDF/A conversion, or custom Ghostscript options.
Features
  • Parallel Processing: Multi-threaded execution for faster batch operations
  • Compression: Multiple quality levels (/screen, /ebook, /printer, /prepress, /default)
  • PDF/A Conversion: Support for PDF/A-1, PDF/A-2, and PDF/A-3 standards1
  • Recursive Search: Process entire directory trees with the -r flag
  • Smart File Management: Keep smaller files automatically or always keep new versions
  • Error Handling: Configurable error behavior (prompt, skip, or abort)
  • Custom Ghostscript Options: Full access to Ghostscript's command-line options
  • Progress Tracking: Real-time progress bars for each file being processed
  • Flexible Output: Add prefixes/suffixes to output filenames, organize into folders
  • Cross-platform: Windows, Linux, and macOS support
Installation
Prerequisites
  1. Python 3.12+: Required to run the tool
  2. Ghostscript: Required for PDF processing. Install from ghostscript.com
Install gs-batch-pdf
Using pipx (recommended)2:
pipx install gs-batch-pdf
Or using pip:
pip install gs-batch-pdf
Usage
The tool is available via two commands: gs_batch or its shorter alias gsb.
Basic Syntax
gsb [OPTIONS] FILES_OR_DIRECTORIES...
or (my preference):
gsb FILES_OR_DIRECTORIES... [OPTIONS]
Quick Start
# Compress all PDFs in current directory (default: /ebook quality)
gsb . --compress
# Compress PDFs recursively in a directory tree
gsb ./docs/ -r --compress
# Convert a single PDF to PDF/A-2
gsb file.pdf --pdfa
# Compress and convert to PDF/A with custom output
gsb *.pdf --compress --pdfa --prefix "processed_"
Note: When using options that can take optional values (like --compress or --pdfa), place them after the file arguments for simplest usage, or see Using Options with File Arguments for alternatives.
Options
Processing Options
  • --compress [LEVEL]: Compress PDFs with quality level
    • Levels: /screen, /ebook (default), /printer, /prepress, /default
    • Use without value for /ebook quality
  • --pdfa [VERSION]: Convert to PDF/A format
    • Versions: 1 (PDF/A-1), 2 (PDF/A-2, default), 3 (PDF/A-3)
    • Use without value for PDF/A-2
  • --options TEXT: Pass arbitrary Ghostscript options
    • Example: --options "-dColorImageResolution=100 -dCompatibilityLevel=1.4"
File Management Options
  • --prefix TEXT: Add prefix to output filenames
    • Can include path: --prefix "output/" creates files in output directory
    • Relative paths calculated from input file location, not current directory
  • --suffix TEXT: Add suffix before file extension
    • Example: --suffix "_compressed" → file_compressed.pdf
  • --keep_smaller / --keep_new: Choose which file to keep (default: --keep_smaller)
    • --keep_smaller: Keep whichever file is smaller (original or processed)
    • --keep_new: Always keep the processed file
    • Note: PDF/A conversion always keeps new file
  • -f, --force: Allow overwriting original files without confirmation
    • Required when no prefix specified and files would be overwritten
Search Options
  • --filter TEXT: Filter files by extension (default: pdf)
    • Supports comma-separated list: --filter pdf,png
  • -r, --recursive: Search directories recursively
    • Without this flag, only processes files in top-level directories
Error Handling Options
  • --on-error [MODE]: Control behavior when file processing errors occur

    • prompt (default): Interactively ask user whether to retry, skip, or abort
    • skip: Automatically skip failed files and continue processing
    • abort: Stop processing immediately on first error
Other Options
  • --timeout INTEGER: Maximum processing time per file in seconds (default: 300)

    • Set to 0 to disable timeout protection
    • Prevents indefinite hangs on problematic PDFs
  • --open_path / --no_open_path: Open output location in file manager (default: enabled)
  • -v, --verbose: Show detailed Ghostscript command output
  • --version: Show version information
  • --help: Display help message
Using Options with File Arguments
When using options that accept optional values (--compress, --pdfa), you have three approaches:
1. Place options after file arguments (recommended):
gsb *.pdf --compress
gsb * --compress --pdfa
2. Provide explicit values:
gsb --compress /ebook *.pdf
gsb --pdfa 2 *.pdf
3. Use -- separator:
gsb --compress -- *.pdf
gsb --pdfa -- *.pdf
Examples
Basic Compression
Compress multiple PDFs with /ebook quality (in-place)3:
gsb file1.pdf file2.pdf file3.pdf --compress
Compress all PDFs in a directory:
gsb . --compress
Compress with specific quality level:
gsb document.pdf --compress /screen
# or with explicit value before files:
gsb --compress /screen *.pdf
PDF/A Conversion
Convert to PDF/A-2 (default):
gsb report.pdf --pdfa
Convert to specific PDF/A version:
gsb document.pdf --pdfa 3
# or with explicit value before files:
gsb --pdfa 3 *.pdf
Compress and convert to PDF/A:
gsb invoice.pdf --compress --pdfa
Recursive Processing
Process entire directory tree:
# Find and compress all PDFs in current directory and subdirectories
gsb . -r --compress
# Process specific directory recursively
gsb ./documents/ -r --compress --pdfa
Process with force (no confirmation):
gsb . -r --compress --pdfa --force
Custom Output Organization
Add prefix to create organized output:
# Add prefix to filenames
gsb *.pdf --prefix "compressed_" --compress
# Create files in subdirectory
gsb *.pdf --prefix "output/" --compress
# Add both prefix and suffix
gsb *.pdf --prefix "processed_" --suffix "_v1" --compress
Keep new files regardless of size:
gsb document.pdf --compress --keep_new
Advanced Ghostscript Options
Apply custom Ghostscript settings:
gsb file.pdf --options "-dCompatibilityLevel=1.4 -dColorImageResolution=72"
Combine compression with custom options:
gsb report.pdf --compress /printer --options "-dCompatibilityLevel=1.7"
Error Handling
Interactive error handling (default):
# Prompts user on each error to retry, skip, or abort
gsb . -r --compress
Skip failed files automatically:
# Useful for batch processing where some files may be corrupted
gsb . -r --compress --on-error skip
Abort on first error:
# Stops immediately if any file fails (useful for CI/CD)
gsb *.pdf --compress --on-error abort
Scripting and Automation
Silent processing for scripts:
gsb *.pdf --compress --force --no_open_path
Automated batch with error skipping:
# Best for unattended processing
gsb . -r --compress --force --no_open_path --on-error skip
Verbose output for debugging:
gsb document.pdf -v --compress --pdfa
Process with custom timeout for large files:
# Set 10 minute timeout for very large PDFs
gsb large-document.pdf --compress --timeout 600
# Disable timeout for files that take a long time
gsb complex-document.pdf --compress --timeout 0
Output
After processing completes, gs-batch-pdf displays a detailed summary table:
Processing 3 file(s):
1) document1.pdf
2) document2.pdf
3) document3.pdf
[Progress bars shown during processing...]
# | Original | New | Ratio | Keeping | Filename
1 | 1,234 KB | 856 KB | 69.400% | new | /path/to/document1.pdf
2 | 789 KB | 654 KB | 82.900% | new | /path/to/document2.pdf
3 | 456 KB | 512 KB | 112.300% | original | /path/to/document3.pdf
Total time: 12.34 seconds

The summary shows:
  • Original: Size of the input file
  • New: Size of the processed file
  • Ratio: New size as percentage of original (lower is better for compression)
  • Keeping: Which version was kept based on --keep_smaller or --keep_new
  • Filename: Absolute path to the output file
By default, the tool opens the output location in your file manager after processing (disable with --no_open_path).
Troubleshooting
Ghostscript Not Found
If you get an error about Ghostscript not being found:
  1. Verify Ghostscript is installed: gs --version (Linux/macOS) or gswin64c --version (Windows)
  2. Ensure Ghostscript is in your system PATH
  3. On Windows, you may need to restart your terminal after installation
PDF/A Conversion Issues
For PDF/A-2 and PDF/A-3 conversion, ensure you're using Ghostscript 10.04.0 or higher:
gs --version
Permission Errors
If you encounter permission errors when processing files:
  • Use --prefix to write to a different directory
  • Check file permissions on both input and output locations
  • On Windows, ensure files aren't open in another program
Timeout Issues
If processing is hanging or taking too long:
  • The default timeout is 5 minutes (300 seconds) per file
  • For large or complex PDFs, increase the timeout: --timeout 600 (10 minutes)
  • To disable timeout protection: --timeout 0
  • Some corrupted PDFs may cause Ghostscript to hang indefinitely - timeout protection will terminate these processes
Contributing
Contributions are welcome! Please feel free to:
  • Report bugs or request features via GitHub Issues
  • Submit Pull Requests for improvements
  • Share feedback and suggestions
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgements
This tool is built on top of Ghostscript, released under the GNU Affero General Public License (AGPL). gs-batch-pdf is a CLI wrapper and is independently licensed under MIT.
Footnotes
  1. Requires Ghostscript version 10.04.0 or higher for correct PDF/A-2 and PDF/A-3 conversion. ↩
  2. pipx installs the package in an isolated virtual environment while making commands globally available. ↩
  3. When no --prefix is provided and files would be overwritten, you'll be prompted for confirmation unless --force is used. ↩
About
No description, website, or topics provided.
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
5 stars
Watchers
1 watching
Forks
0 forks
Report repository
Releases
Packages
Used by
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
GitHub - kompre/gs-batch · GitHub
Skip to content
BranchesTags
Repository files navigation
gs-batch-pdf
A command-line tool for batch processing PDF files using Ghostscript with parallel execution. Process multiple PDFs simultaneously while applying compression, PDF/A conversion, or custom Ghostscript options.
Features
  • Parallel Processing: Multi-threaded execution for faster batch operations
  • Compression: Multiple quality levels (/screen, /ebook, /printer, /prepress, /default)
  • PDF/A Conversion: Support for PDF/A-1, PDF/A-2, and PDF/A-3 standards1
  • Recursive Search: Process entire directory trees with the -r flag
  • Smart File Management: Keep smaller files automatically or always keep new versions
  • Error Handling: Configurable error behavior (prompt, skip, or abort)
  • Custom Ghostscript Options: Full access to Ghostscript's command-line options
  • Progress Tracking: Real-time progress bars for each file being processed
  • Flexible Output: Add prefixes/suffixes to output filenames, organize into folders
  • Cross-platform: Windows, Linux, and macOS support
Installation
Prerequisites
  1. Python 3.12+: Required to run the tool
  2. Ghostscript: Required for PDF processing. Install from ghostscript.com
Install gs-batch-pdf
Using pipx (recommended)2:
pipx install gs-batch-pdf
Or using pip:
pip install gs-batch-pdf
Usage
The tool is available via two commands: gs_batch or its shorter alias gsb.
Basic Syntax
gsb [OPTIONS] FILES_OR_DIRECTORIES...
or (my preference):
gsb FILES_OR_DIRECTORIES... [OPTIONS]
Quick Start
# Compress all PDFs in current directory (default: /ebook quality)
gsb . --compress
# Compress PDFs recursively in a directory tree
gsb ./docs/ -r --compress
# Convert a single PDF to PDF/A-2
gsb file.pdf --pdfa
# Compress and convert to PDF/A with custom output
gsb *.pdf --compress --pdfa --prefix "processed_"
Note: When using options that can take optional values (like --compress or --pdfa), place them after the file arguments for simplest usage, or see Using Options with File Arguments for alternatives.
Options
Processing Options
  • --compress [LEVEL]: Compress PDFs with quality level
    • Levels: /screen, /ebook (default), /printer, /prepress, /default
    • Use without value for /ebook quality
  • --pdfa [VERSION]: Convert to PDF/A format
    • Versions: 1 (PDF/A-1), 2 (PDF/A-2, default), 3 (PDF/A-3)
    • Use without value for PDF/A-2
  • --options TEXT: Pass arbitrary Ghostscript options
    • Example: --options "-dColorImageResolution=100 -dCompatibilityLevel=1.4"
File Management Options
  • --prefix TEXT: Add prefix to output filenames
    • Can include path: --prefix "output/" creates files in output directory
    • Relative paths calculated from input file location, not current directory
  • --suffix TEXT: Add suffix before file extension
    • Example: --suffix "_compressed" → file_compressed.pdf
  • --keep_smaller / --keep_new: Choose which file to keep (default: --keep_smaller)
    • --keep_smaller: Keep whichever file is smaller (original or processed)
    • --keep_new: Always keep the processed file
    • Note: PDF/A conversion always keeps new file
  • -f, --force: Allow overwriting original files without confirmation
    • Required when no prefix specified and files would be overwritten
Search Options
  • --filter TEXT: Filter files by extension (default: pdf)
    • Supports comma-separated list: --filter pdf,png
  • -r, --recursive: Search directories recursively
    • Without this flag, only processes files in top-level directories
Error Handling Options
  • --on-error [MODE]: Control behavior when file processing errors occur

    • prompt (default): Interactively ask user whether to retry, skip, or abort
    • skip: Automatically skip failed files and continue processing
    • abort: Stop processing immediately on first error
Other Options
  • --timeout INTEGER: Maximum processing time per file in seconds (default: 300)

    • Set to 0 to disable timeout protection
    • Prevents indefinite hangs on problematic PDFs
  • --open_path / --no_open_path: Open output location in file manager (default: enabled)
  • -v, --verbose: Show detailed Ghostscript command output
  • --version: Show version information
  • --help: Display help message
Using Options with File Arguments
When using options that accept optional values (--compress, --pdfa), you have three approaches:
1. Place options after file arguments (recommended):
gsb *.pdf --compress
gsb * --compress --pdfa
2. Provide explicit values:
gsb --compress /ebook *.pdf
gsb --pdfa 2 *.pdf
3. Use -- separator:
gsb --compress -- *.pdf
gsb --pdfa -- *.pdf
Examples
Basic Compression
Compress multiple PDFs with /ebook quality (in-place)3:
gsb file1.pdf file2.pdf file3.pdf --compress
Compress all PDFs in a directory:
gsb . --compress
Compress with specific quality level:
gsb document.pdf --compress /screen
# or with explicit value before files:
gsb --compress /screen *.pdf
PDF/A Conversion
Convert to PDF/A-2 (default):
gsb report.pdf --pdfa
Convert to specific PDF/A version:
gsb document.pdf --pdfa 3
# or with explicit value before files:
gsb --pdfa 3 *.pdf
Compress and convert to PDF/A:
gsb invoice.pdf --compress --pdfa
Recursive Processing
Process entire directory tree:
# Find and compress all PDFs in current directory and subdirectories
gsb . -r --compress
# Process specific directory recursively
gsb ./documents/ -r --compress --pdfa
Process with force (no confirmation):
gsb . -r --compress --pdfa --force
Custom Output Organization
Add prefix to create organized output:
# Add prefix to filenames
gsb *.pdf --prefix "compressed_" --compress
# Create files in subdirectory
gsb *.pdf --prefix "output/" --compress
# Add both prefix and suffix
gsb *.pdf --prefix "processed_" --suffix "_v1" --compress
Keep new files regardless of size:
gsb document.pdf --compress --keep_new
Advanced Ghostscript Options
Apply custom Ghostscript settings:
gsb file.pdf --options "-dCompatibilityLevel=1.4 -dColorImageResolution=72"
Combine compression with custom options:
gsb report.pdf --compress /printer --options "-dCompatibilityLevel=1.7"
Error Handling
Interactive error handling (default):
# Prompts user on each error to retry, skip, or abort
gsb . -r --compress
Skip failed files automatically:
# Useful for batch processing where some files may be corrupted
gsb . -r --compress --on-error skip
Abort on first error:
# Stops immediately if any file fails (useful for CI/CD)
gsb *.pdf --compress --on-error abort
Scripting and Automation
Silent processing for scripts:
gsb *.pdf --compress --force --no_open_path
Automated batch with error skipping:
# Best for unattended processing
gsb . -r --compress --force --no_open_path --on-error skip
Verbose output for debugging:
gsb document.pdf -v --compress --pdfa
Process with custom timeout for large files:
# Set 10 minute timeout for very large PDFs
gsb large-document.pdf --compress --timeout 600
# Disable timeout for files that take a long time
gsb complex-document.pdf --compress --timeout 0
Output
After processing completes, gs-batch-pdf displays a detailed summary table:
Processing 3 file(s):
1) document1.pdf
2) document2.pdf
3) document3.pdf
[Progress bars shown during processing...]
# | Original | New | Ratio | Keeping | Filename
1 | 1,234 KB | 856 KB | 69.400% | new | /path/to/document1.pdf
2 | 789 KB | 654 KB | 82.900% | new | /path/to/document2.pdf
3 | 456 KB | 512 KB | 112.300% | original | /path/to/document3.pdf
Total time: 12.34 seconds

The summary shows:
  • Original: Size of the input file
  • New: Size of the processed file
  • Ratio: New size as percentage of original (lower is better for compression)
  • Keeping: Which version was kept based on --keep_smaller or --keep_new
  • Filename: Absolute path to the output file
By default, the tool opens the output location in your file manager after processing (disable with --no_open_path).
Troubleshooting
Ghostscript Not Found
If you get an error about Ghostscript not being found:
  1. Verify Ghostscript is installed: gs --version (Linux/macOS) or gswin64c --version (Windows)
  2. Ensure Ghostscript is in your system PATH
  3. On Windows, you may need to restart your terminal after installation
PDF/A Conversion Issues
For PDF/A-2 and PDF/A-3 conversion, ensure you're using Ghostscript 10.04.0 or higher:
gs --version
Permission Errors
If you encounter permission errors when processing files:
  • Use --prefix to write to a different directory
  • Check file permissions on both input and output locations
  • On Windows, ensure files aren't open in another program
Timeout Issues
If processing is hanging or taking too long:
  • The default timeout is 5 minutes (300 seconds) per file
  • For large or complex PDFs, increase the timeout: --timeout 600 (10 minutes)
  • To disable timeout protection: --timeout 0
  • Some corrupted PDFs may cause Ghostscript to hang indefinitely - timeout protection will terminate these processes
Contributing
Contributions are welcome! Please feel free to:
  • Report bugs or request features via GitHub Issues
  • Submit Pull Requests for improvements
  • Share feedback and suggestions
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgements
This tool is built on top of Ghostscript, released under the GNU Affero General Public License (AGPL). gs-batch-pdf is a CLI wrapper and is independently licensed under MIT.
Footnotes
  1. Requires Ghostscript version 10.04.0 or higher for correct PDF/A-2 and PDF/A-3 conversion. ↩
  2. pipx installs the package in an isolated virtual environment while making commands globally available. ↩
  3. When no --prefix is provided and files would be overwritten, you'll be prompted for confirmation unless --force is used. ↩
About
No description, website, or topics provided.
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
5 stars
Watchers
1 watching
Forks
0 forks
Report repository
Releases
Packages
Used by
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
GitHub - kompre/gs-batch · GitHub
Skip to content
BranchesTags
Repository files navigation
gs-batch-pdf
A command-line tool for batch processing PDF files using Ghostscript with parallel execution. Process multiple PDFs simultaneously while applying compression, PDF/A conversion, or custom Ghostscript options.
Features
  • Parallel Processing: Multi-threaded execution for faster batch operations
  • Compression: Multiple quality levels (/screen, /ebook, /printer, /prepress, /default)
  • PDF/A Conversion: Support for PDF/A-1, PDF/A-2, and PDF/A-3 standards1
  • Recursive Search: Process entire directory trees with the -r flag
  • Smart File Management: Keep smaller files automatically or always keep new versions
  • Error Handling: Configurable error behavior (prompt, skip, or abort)
  • Custom Ghostscript Options: Full access to Ghostscript's command-line options
  • Progress Tracking: Real-time progress bars for each file being processed
  • Flexible Output: Add prefixes/suffixes to output filenames, organize into folders
  • Cross-platform: Windows, Linux, and macOS support
Installation
Prerequisites
  1. Python 3.12+: Required to run the tool
  2. Ghostscript: Required for PDF processing. Install from ghostscript.com
Install gs-batch-pdf
Using pipx (recommended)2:
pipx install gs-batch-pdf
Or using pip:
pip install gs-batch-pdf
Usage
The tool is available via two commands: gs_batch or its shorter alias gsb.
Basic Syntax
gsb [OPTIONS] FILES_OR_DIRECTORIES...
or (my preference):
gsb FILES_OR_DIRECTORIES... [OPTIONS]
Quick Start
# Compress all PDFs in current directory (default: /ebook quality)
gsb . --compress
# Compress PDFs recursively in a directory tree
gsb ./docs/ -r --compress
# Convert a single PDF to PDF/A-2
gsb file.pdf --pdfa
# Compress and convert to PDF/A with custom output
gsb *.pdf --compress --pdfa --prefix "processed_"
Note: When using options that can take optional values (like --compress or --pdfa), place them after the file arguments for simplest usage, or see Using Options with File Arguments for alternatives.
Options
Processing Options
  • --compress [LEVEL]: Compress PDFs with quality level
    • Levels: /screen, /ebook (default), /printer, /prepress, /default
    • Use without value for /ebook quality
  • --pdfa [VERSION]: Convert to PDF/A format
    • Versions: 1 (PDF/A-1), 2 (PDF/A-2, default), 3 (PDF/A-3)
    • Use without value for PDF/A-2
  • --options TEXT: Pass arbitrary Ghostscript options
    • Example: --options "-dColorImageResolution=100 -dCompatibilityLevel=1.4"
File Management Options
  • --prefix TEXT: Add prefix to output filenames
    • Can include path: --prefix "output/" creates files in output directory
    • Relative paths calculated from input file location, not current directory
  • --suffix TEXT: Add suffix before file extension
    • Example: --suffix "_compressed" → file_compressed.pdf
  • --keep_smaller / --keep_new: Choose which file to keep (default: --keep_smaller)
    • --keep_smaller: Keep whichever file is smaller (original or processed)
    • --keep_new: Always keep the processed file
    • Note: PDF/A conversion always keeps new file
  • -f, --force: Allow overwriting original files without confirmation
    • Required when no prefix specified and files would be overwritten
Search Options
  • --filter TEXT: Filter files by extension (default: pdf)
    • Supports comma-separated list: --filter pdf,png
  • -r, --recursive: Search directories recursively
    • Without this flag, only processes files in top-level directories
Error Handling Options
  • --on-error [MODE]: Control behavior when file processing errors occur

    • prompt (default): Interactively ask user whether to retry, skip, or abort
    • skip: Automatically skip failed files and continue processing
    • abort: Stop processing immediately on first error
Other Options
  • --timeout INTEGER: Maximum processing time per file in seconds (default: 300)

    • Set to 0 to disable timeout protection
    • Prevents indefinite hangs on problematic PDFs
  • --open_path / --no_open_path: Open output location in file manager (default: enabled)
  • -v, --verbose: Show detailed Ghostscript command output
  • --version: Show version information
  • --help: Display help message
Using Options with File Arguments
When using options that accept optional values (--compress, --pdfa), you have three approaches:
1. Place options after file arguments (recommended):
gsb *.pdf --compress
gsb * --compress --pdfa
2. Provide explicit values:
gsb --compress /ebook *.pdf
gsb --pdfa 2 *.pdf
3. Use -- separator:
gsb --compress -- *.pdf
gsb --pdfa -- *.pdf
Examples
Basic Compression
Compress multiple PDFs with /ebook quality (in-place)3:
gsb file1.pdf file2.pdf file3.pdf --compress
Compress all PDFs in a directory:
gsb . --compress
Compress with specific quality level:
gsb document.pdf --compress /screen
# or with explicit value before files:
gsb --compress /screen *.pdf
PDF/A Conversion
Convert to PDF/A-2 (default):
gsb report.pdf --pdfa
Convert to specific PDF/A version:
gsb document.pdf --pdfa 3
# or with explicit value before files:
gsb --pdfa 3 *.pdf
Compress and convert to PDF/A:
gsb invoice.pdf --compress --pdfa
Recursive Processing
Process entire directory tree:
# Find and compress all PDFs in current directory and subdirectories
gsb . -r --compress
# Process specific directory recursively
gsb ./documents/ -r --compress --pdfa
Process with force (no confirmation):
gsb . -r --compress --pdfa --force
Custom Output Organization
Add prefix to create organized output:
# Add prefix to filenames
gsb *.pdf --prefix "compressed_" --compress
# Create files in subdirectory
gsb *.pdf --prefix "output/" --compress
# Add both prefix and suffix
gsb *.pdf --prefix "processed_" --suffix "_v1" --compress
Keep new files regardless of size:
gsb document.pdf --compress --keep_new
Advanced Ghostscript Options
Apply custom Ghostscript settings:
gsb file.pdf --options "-dCompatibilityLevel=1.4 -dColorImageResolution=72"
Combine compression with custom options:
gsb report.pdf --compress /printer --options "-dCompatibilityLevel=1.7"
Error Handling
Interactive error handling (default):
# Prompts user on each error to retry, skip, or abort
gsb . -r --compress
Skip failed files automatically:
# Useful for batch processing where some files may be corrupted
gsb . -r --compress --on-error skip
Abort on first error:
# Stops immediately if any file fails (useful for CI/CD)
gsb *.pdf --compress --on-error abort
Scripting and Automation
Silent processing for scripts:
gsb *.pdf --compress --force --no_open_path
Automated batch with error skipping:
# Best for unattended processing
gsb . -r --compress --force --no_open_path --on-error skip
Verbose output for debugging:
gsb document.pdf -v --compress --pdfa
Process with custom timeout for large files:
# Set 10 minute timeout for very large PDFs
gsb large-document.pdf --compress --timeout 600
# Disable timeout for files that take a long time
gsb complex-document.pdf --compress --timeout 0
Output
After processing completes, gs-batch-pdf displays a detailed summary table:
Processing 3 file(s):
1) document1.pdf
2) document2.pdf
3) document3.pdf
[Progress bars shown during processing...]
# | Original | New | Ratio | Keeping | Filename
1 | 1,234 KB | 856 KB | 69.400% | new | /path/to/document1.pdf
2 | 789 KB | 654 KB | 82.900% | new | /path/to/document2.pdf
3 | 456 KB | 512 KB | 112.300% | original | /path/to/document3.pdf
Total time: 12.34 seconds

The summary shows:
  • Original: Size of the input file
  • New: Size of the processed file
  • Ratio: New size as percentage of original (lower is better for compression)
  • Keeping: Which version was kept based on --keep_smaller or --keep_new
  • Filename: Absolute path to the output file
By default, the tool opens the output location in your file manager after processing (disable with --no_open_path).
Troubleshooting
Ghostscript Not Found
If you get an error about Ghostscript not being found:
  1. Verify Ghostscript is installed: gs --version (Linux/macOS) or gswin64c --version (Windows)
  2. Ensure Ghostscript is in your system PATH
  3. On Windows, you may need to restart your terminal after installation
PDF/A Conversion Issues
For PDF/A-2 and PDF/A-3 conversion, ensure you're using Ghostscript 10.04.0 or higher:
gs --version
Permission Errors
If you encounter permission errors when processing files:
  • Use --prefix to write to a different directory
  • Check file permissions on both input and output locations
  • On Windows, ensure files aren't open in another program
Timeout Issues
If processing is hanging or taking too long:
  • The default timeout is 5 minutes (300 seconds) per file
  • For large or complex PDFs, increase the timeout: --timeout 600 (10 minutes)
  • To disable timeout protection: --timeout 0
  • Some corrupted PDFs may cause Ghostscript to hang indefinitely - timeout protection will terminate these processes
Contributing
Contributions are welcome! Please feel free to:
  • Report bugs or request features via GitHub Issues
  • Submit Pull Requests for improvements
  • Share feedback and suggestions
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgements
This tool is built on top of Ghostscript, released under the GNU Affero General Public License (AGPL). gs-batch-pdf is a CLI wrapper and is independently licensed under MIT.
Footnotes
  1. Requires Ghostscript version 10.04.0 or higher for correct PDF/A-2 and PDF/A-3 conversion. ↩
  2. pipx installs the package in an isolated virtual environment while making commands globally available. ↩
  3. When no --prefix is provided and files would be overwritten, you'll be prompted for confirmation unless --force is used. ↩
About
No description, website, or topics provided.
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
5 stars
Watchers
1 watching
Forks
0 forks
Report repository
Releases
Packages
Used by
Contributors
Languages

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
GitHub - kompre/gs-batch · GitHub
Skip to content
BranchesTags
Repository files navigation
gs-batch-pdf
A command-line tool for batch processing PDF files using Ghostscript with parallel execution. Process multiple PDFs simultaneously while applying compression, PDF/A conversion, or custom Ghostscript options.
Features
  • Parallel Processing: Multi-threaded execution for faster batch operations
  • Compression: Multiple quality levels (/screen, /ebook, /printer, /prepress, /default)
  • PDF/A Conversion: Support for PDF/A-1, PDF/A-2, and PDF/A-3 standards1
  • Recursive Search: Process entire directory trees with the -r flag
  • Smart File Management: Keep smaller files automatically or always keep new versions
  • Error Handling: Configurable error behavior (prompt, skip, or abort)
  • Custom Ghostscript Options: Full access to Ghostscript's command-line options
  • Progress Tracking: Real-time progress bars for each file being processed
  • Flexible Output: Add prefixes/suffixes to output filenames, organize into folders
  • Cross-platform: Windows, Linux, and macOS support
Installation
Prerequisites
  1. Python 3.12+: Required to run the tool
  2. Ghostscript: Required for PDF processing. Install from ghostscript.com
Install gs-batch-pdf
Using pipx (recommended)2:
pipx install gs-batch-pdf
Or using pip:
pip install gs-batch-pdf
Usage
The tool is available via two commands: gs_batch or its shorter alias gsb.
Basic Syntax
gsb [OPTIONS] FILES_OR_DIRECTORIES...
or (my preference):
gsb FILES_OR_DIRECTORIES... [OPTIONS]
Quick Start
# Compress all PDFs in current directory (default: /ebook quality)
gsb . --compress
# Compress PDFs recursively in a directory tree
gsb ./docs/ -r --compress
# Convert a single PDF to PDF/A-2
gsb file.pdf --pdfa
# Compress and convert to PDF/A with custom output
gsb *.pdf --compress --pdfa --prefix "processed_"
Note: When using options that can take optional values (like --compress or --pdfa), place them after the file arguments for simplest usage, or see Using Options with File Arguments for alternatives.
Options
Processing Options
  • --compress [LEVEL]: Compress PDFs with quality level
    • Levels: /screen, /ebook (default), /printer, /prepress, /default
    • Use without value for /ebook quality
  • --pdfa [VERSION]: Convert to PDF/A format
    • Versions: 1 (PDF/A-1), 2 (PDF/A-2, default), 3 (PDF/A-3)
    • Use without value for PDF/A-2
  • --options TEXT: Pass arbitrary Ghostscript options
    • Example: --options "-dColorImageResolution=100 -dCompatibilityLevel=1.4"
File Management Options
  • --prefix TEXT: Add prefix to output filenames
    • Can include path: --prefix "output/" creates files in output directory
    • Relative paths calculated from input file location, not current directory
  • --suffix TEXT: Add suffix before file extension
    • Example: --suffix "_compressed" → file_compressed.pdf
  • --keep_smaller / --keep_new: Choose which file to keep (default: --keep_smaller)
    • --keep_smaller: Keep whichever file is smaller (original or processed)
    • --keep_new: Always keep the processed file
    • Note: PDF/A conversion always keeps new file
  • -f, --force: Allow overwriting original files without confirmation
    • Required when no prefix specified and files would be overwritten
Search Options
  • --filter TEXT: Filter files by extension (default: pdf)
    • Supports comma-separated list: --filter pdf,png
  • -r, --recursive: Search directories recursively
    • Without this flag, only processes files in top-level directories
Error Handling Options
  • --on-error [MODE]: Control behavior when file processing errors occur

    • prompt (default): Interactively ask user whether to retry, skip, or abort
    • skip: Automatically skip failed files and continue processing
    • abort: Stop processing immediately on first error
Other Options
  • --timeout INTEGER: Maximum processing time per file in seconds (default: 300)

    • Set to 0 to disable timeout protection
    • Prevents indefinite hangs on problematic PDFs
  • --open_path / --no_open_path: Open output location in file manager (default: enabled)
  • -v, --verbose: Show detailed Ghostscript command output
  • --version: Show version information
  • --help: Display help message
Using Options with File Arguments
When using options that accept optional values (--compress, --pdfa), you have three approaches:
1. Place options after file arguments (recommended):
gsb *.pdf --compress
gsb * --compress --pdfa
2. Provide explicit values:
gsb --compress /ebook *.pdf
gsb --pdfa 2 *.pdf
3. Use -- separator:
gsb --compress -- *.pdf
gsb --pdfa -- *.pdf
Examples
Basic Compression
Compress multiple PDFs with /ebook quality (in-place)3:
gsb file1.pdf file2.pdf file3.pdf --compress
Compress all PDFs in a directory:
gsb . --compress
Compress with specific quality level:
gsb document.pdf --compress /screen
# or with explicit value before files:
gsb --compress /screen *.pdf
PDF/A Conversion
Convert to PDF/A-2 (default):
gsb report.pdf --pdfa
Convert to specific PDF/A version:
gsb document.pdf --pdfa 3
# or with explicit value before files:
gsb --pdfa 3 *.pdf
Compress and convert to PDF/A:
gsb invoice.pdf --compress --pdfa
Recursive Processing
Process entire directory tree:
# Find and compress all PDFs in current directory and subdirectories
gsb . -r --compress
# Process specific directory recursively
gsb ./documents/ -r --compress --pdfa
Process with force (no confirmation):
gsb . -r --compress --pdfa --force
Custom Output Organization
Add prefix to create organized output:
# Add prefix to filenames
gsb *.pdf --prefix "compressed_" --compress
# Create files in subdirectory
gsb *.pdf --prefix "output/" --compress
# Add both prefix and suffix
gsb *.pdf --prefix "processed_" --suffix "_v1" --compress
Keep new files regardless of size:
gsb document.pdf --compress --keep_new
Advanced Ghostscript Options
Apply custom Ghostscript settings:
gsb file.pdf --options "-dCompatibilityLevel=1.4 -dColorImageResolution=72"
Combine compression with custom options:
gsb report.pdf --compress /printer --options "-dCompatibilityLevel=1.7"
Error Handling
Interactive error handling (default):
# Prompts user on each error to retry, skip, or abort
gsb . -r --compress
Skip failed files automatically:
# Useful for batch processing where some files may be corrupted
gsb . -r --compress --on-error skip
Abort on first error:
# Stops immediately if any file fails (useful for CI/CD)
gsb *.pdf --compress --on-error abort
Scripting and Automation
Silent processing for scripts:
gsb *.pdf --compress --force --no_open_path
Automated batch with error skipping:
# Best for unattended processing
gsb . -r --compress --force --no_open_path --on-error skip
Verbose output for debugging:
gsb document.pdf -v --compress --pdfa
Process with custom timeout for large files:
# Set 10 minute timeout for very large PDFs
gsb large-document.pdf --compress --timeout 600
# Disable timeout for files that take a long time
gsb complex-document.pdf --compress --timeout 0
Output
After processing completes, gs-batch-pdf displays a detailed summary table:
Processing 3 file(s):
1) document1.pdf
2) document2.pdf
3) document3.pdf
[Progress bars shown during processing...]
# | Original | New | Ratio | Keeping | Filename
1 | 1,234 KB | 856 KB | 69.400% | new | /path/to/document1.pdf
2 | 789 KB | 654 KB | 82.900% | new | /path/to/document2.pdf
3 | 456 KB | 512 KB | 112.300% | original | /path/to/document3.pdf
Total time: 12.34 seconds

The summary shows:
  • Original: Size of the input file
  • New: Size of the processed file
  • Ratio: New size as percentage of original (lower is better for compression)
  • Keeping: Which version was kept based on --keep_smaller or --keep_new
  • Filename: Absolute path to the output file
By default, the tool opens the output location in your file manager after processing (disable with --no_open_path).
Troubleshooting
Ghostscript Not Found
If you get an error about Ghostscript not being found:
  1. Verify Ghostscript is installed: gs --version (Linux/macOS) or gswin64c --version (Windows)
  2. Ensure Ghostscript is in your system PATH
  3. On Windows, you may need to restart your terminal after installation
PDF/A Conversion Issues
For PDF/A-2 and PDF/A-3 conversion, ensure you're using Ghostscript 10.04.0 or higher:
gs --version
Permission Errors
If you encounter permission errors when processing files:
  • Use --prefix to write to a different directory
  • Check file permissions on both input and output locations
  • On Windows, ensure files aren't open in another program
Timeout Issues
If processing is hanging or taking too long:
  • The default timeout is 5 minutes (300 seconds) per file
  • For large or complex PDFs, increase the timeout: --timeout 600 (10 minutes)
  • To disable timeout protection: --timeout 0
  • Some corrupted PDFs may cause Ghostscript to hang indefinitely - timeout protection will terminate these processes
Contributing
Contributions are welcome! Please feel free to:
  • Report bugs or request features via GitHub Issues
  • Submit Pull Requests for improvements
  • Share feedback and suggestions
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgements
This tool is built on top of Ghostscript, released under the GNU Affero General Public License (AGPL). gs-batch-pdf is a CLI wrapper and is independently licensed under MIT.
Footnotes
  1. Requires Ghostscript version 10.04.0 or higher for correct PDF/A-2 and PDF/A-3 conversion. ↩
  2. pipx installs the package in an isolated virtual environment while making commands globally available. ↩
  3. When no --prefix is provided and files would be overwritten, you'll be prompted for confirmation unless --force is used. ↩
About
No description, website, or topics provided.
Resources
Readme
MIT license
Contributing
Contributing
Activity
Stars
5 stars
Watchers
1 watching
Forks
0 forks
Report repository
Releases
Packages
Used by
Contributors
Languages