{"id":50721029,"url":"https://github.com/bastienlc/pdf-watermark","last_synced_at":"2026-06-27T01:01:21.750Z","repository":{"id":176908508,"uuid":"658968277","full_name":"bastienlc/pdf-watermark","owner":"bastienlc","description":"A python CLI tool to add watermarks to a PDF","archived":false,"fork":false,"pushed_at":"2026-06-06T16:48:59.000Z","size":1077,"stargazers_count":78,"open_issues_count":2,"forks_count":12,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-06-06T18:16:14.484Z","etag":null,"topics":["pdf","pdf-watermark","python","watermark","watermark-pdf","watermark-pdf-files","watermarking"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bastienlc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-06-26T22:00:16.000Z","updated_at":"2026-06-06T16:47:42.000Z","dependencies_parsed_at":"2024-02-15T10:31:16.506Z","dependency_job_id":"e4d66a86-84bf-45dc-b4ff-8c994a9dc625","html_url":"https://github.com/bastienlc/pdf-watermark","commit_stats":null,"previous_names":["bastienlc/pdf-watermark"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/bastienlc/pdf-watermark","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bastienlc%2Fpdf-watermark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bastienlc%2Fpdf-watermark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bastienlc%2Fpdf-watermark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bastienlc%2Fpdf-watermark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bastienlc","download_url":"https://codeload.github.com/bastienlc/pdf-watermark/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bastienlc%2Fpdf-watermark/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34838035,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pdf","pdf-watermark","python","watermark","watermark-pdf","watermark-pdf-files","watermarking"],"created_at":"2026-06-10T00:00:33.540Z","updated_at":"2026-06-27T01:01:21.676Z","avatar_url":"https://github.com/bastienlc.png","language":"Python","funding_links":[],"categories":["docs"],"sub_categories":[],"readme":"# pdf-watermark\n\nA python CLI tool to add watermarks to a PDF. Allows for processing whole directories while keeping the directory structure.\n\n## Description\n\nThere are multiple similar tools out there but I couldn't find one that really suited my needs. This project also serves as an excuse to play with building and distributing a python CLI tool.\n\nWith this tool you can add a watermark to a PDF file. The watermark can either be a text string that you provide, or an image (PNG being the recommanded format).\n\nThis tool provides two commands.\n\n- **insert**: The watermark is placed once on each page at a specific position.\n- **grid**: The watermark is repeated multiple times on each page in a grid pattern.\n\nBelow is an example of a PDF before using this tool, after using this tool with the _grid_ command and a text watermark, and after using this tool with the _grid_ command and an image watermark.\n\n\u003cp align=\"middle\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/bastienlc/pdf-watermark/master/images/before.png\" width=\"29%\" /\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/bastienlc/pdf-watermark/master/images/text.png\" width=\"29%\" /\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/bastienlc/pdf-watermark/master/images/image.png\" width=\"29%\" /\u003e\n\u003c/p\u003e\n\nMany options are available to customize the watermark, such as the position, the opacity, the angle, the color, the font, the size, etc. A detailed list of options is available below.\n\n## Getting Started\n\n### Dependencies\n\n- This project was built with python 3.11. However it should also run just fine with older versions.\n- See `requirements.txt` for the list of dependencies.\n- Some options require parts of the `poppler` library to be installed (--save-as-image and --unselectable). Please refer to the [pdf2image](https://pypi.org/project/pdf2image/) or [poppler](https://poppler.freedesktop.org/) documentation for installation instructions.\n\n### Installing\n\nThis package is available on PyPi.\n\n```\npip install pdf-watermark\n```\n\nThe project can also be used with `uvx` without installing it manually:\n\n```\nuvx run pdf-watermark \u003ccommand and options\u003e\n```\n\n### Usage\n\n**TLDR**\n\n```bash\nwatermark grid input.pdf \"watermark text\" -s output.pdf # Grid pattern for a single file\nwatermark insert input_folder \"watermark_image.png\" # Insert image for a whole directory, overwriting the input files\n```\n\n**Detailed usage**\n\n```\nUsage: watermark [OPTIONS] COMMAND [ARGS]...\n\n  Add a watermark to one or more PDF files.\n\n  The watermark can be repeated in a grid pattern using the grid command, or\n  inserted at a specific position using the insert command.\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  grid    Add a watermark in a grid pattern.\n  insert  Add a watermark at a specific position.\n```\n\n**insert** command:\n\n```\nUsage: watermark insert [OPTIONS] FILE WATERMARK\n\n  Add a watermark at a specific position.\n\n  Add a WATERMARK to one or more PDF files referenced by FILE. WATERMARK can\n  be either a string or a path to an image file. FILE can be a single file or\n  a directory, in which case all PDF files in the directory will be\n  watermarked.\n\nOptions:\n  -s, --save PATH                 File or folder to save results to. By\n                                  default, the input files are overwritten.\n  --dry-run                       Enumerate affected files without modifying\n                                  them.\n  --workers INTEGER               Number of parallel workers to use. This can\n                                  speed up processing of multiple files.\n                                  [default: 1]\n  --verbose BOOLEAN               Print information about the files being\n                                  processed.  [default: True]\n  -y, --y FLOAT                   Position of the watermark with respect to\n                                  the vertical direction. Must be between 0\n                                  and 1.  [default: 0.5]\n  -x, --x FLOAT                   Position of the watermark with respect to\n                                  the horizontal direction. Must be between 0\n                                  and 1.  [default: 0.5]\n  -ha, --horizontal-alignment TEXT\n                                  Alignment of the watermark with respect to\n                                  the horizontal direction. Can be one of\n                                  'left', 'right' and 'center'.  [default:\n                                  center]\n  -o, --opacity FLOAT             Watermark opacity between 0 (invisible) and\n                                  1 (no transparency).  [default: 0.1]\n  -a, --angle FLOAT               Watermark inclination in degrees.  [default:\n                                  45]\n  -tc, --text-color TEXT          Text color in hexadecimal format, e.g.\n                                  #000000.  [default: #000000]\n  -tf, --text-font TEXT           Text font to use. Supported fonts are those\n                                  supported by reportlab, or available on the\n                                  system or in the custom fonts folder.\n                                  [default: Helvetica]\n  -ts, --text-size INTEGER        Text font size.  [default: 12]\n  --unselectable                  Make the watermark text unselectable. This\n                                  works by drawing the text as an image, and\n                                  thus results in a larger file size.\n  -is, --image-scale FLOAT        Scale factor for the image. Note that before\n                                  this factor is applied, the image is already\n                                  scaled down to fit in the boxes.  [default:\n                                  1]\n  --save-as-image                 Convert each PDF page to an image. This\n                                  makes removing the watermark more difficult\n                                  but also increases the file size.\n  --dpi INTEGER                   DPI to use when saving the PDF as an image.\n                                  [default: 300]\n  --custom-fonts-folder PATH      Folder path containing custom font files\n                                  (TTF, OTF, etc.) to search for non-standard\n                                  fonts.\n  --help                          Show this message and exit.\n```\n\n**grid** command:\n\n```\nUsage: watermark grid [OPTIONS] FILE WATERMARK\n\n  Add a watermark in a grid pattern.\n\n  Add a WATERMARK to one or more PDF files referenced by FILE. WATERMARK can\n  be either a string or a path to an image file. FILE can be a single file or\n  a directory, in which case all PDF files in the directory will be\n  watermarked.\n\nOptions:\n  -s, --save PATH                 File or folder to save results to. By\n                                  default, the input files are overwritten.\n  --dry-run                       Enumerate affected files without modifying\n                                  them.\n  --workers INTEGER               Number of parallel workers to use. This can\n                                  speed up processing of multiple files.\n                                  [default: 1]\n  --verbose BOOLEAN               Print information about the files being\n                                  processed.  [default: True]\n  -h, --horizontal-boxes INTEGER  Number of repetitions of the watermark along\n                                  the horizontal direction.  [default: 3]\n  -v, --vertical-boxes INTEGER    Number of repetitions of the watermark along\n                                  the vertical direction.  [default: 6]\n  -m, --margin                    Wether to leave a margin around the page or\n                                  not. When False (default), the watermark\n                                  will be cut on the PDF edges.\n  -o, --opacity FLOAT             Watermark opacity between 0 (invisible) and\n                                  1 (no transparency).  [default: 0.1]\n  -a, --angle FLOAT               Watermark inclination in degrees.  [default:\n                                  45]\n  -tc, --text-color TEXT          Text color in hexadecimal format, e.g.\n                                  #000000.  [default: #000000]\n  -tf, --text-font TEXT           Text font to use. Supported fonts are those\n                                  supported by reportlab, or available on the\n                                  system or in the custom fonts folder.\n                                  [default: Helvetica]\n  -ts, --text-size INTEGER        Text font size.  [default: 12]\n  --unselectable                  Make the watermark text unselectable. This\n                                  works by drawing the text as an image, and\n                                  thus results in a larger file size.\n  -is, --image-scale FLOAT        Scale factor for the image. Note that before\n                                  this factor is applied, the image is already\n                                  scaled down to fit in the boxes.  [default:\n                                  1]\n  --save-as-image                 Convert each PDF page to an image. This\n                                  makes removing the watermark more difficult\n                                  but also increases the file size.\n  --dpi INTEGER                   DPI to use when saving the PDF as an image.\n                                  [default: 300]\n  --custom-fonts-folder PATH      Folder path containing custom font files\n                                  (TTF, OTF, etc.) to search for non-standard\n                                  fonts.\n  --help                          Show this message and exit.\n```\n\n### Fonts\n\n\u003cdetails\u003e\n\u003csummary\u003eThe default fonts provided by reportlab are available, including non-Latin fonts for Chinese, Japanese and Korean characters.\n\u003c/summary\u003e\n\n- Helvetica\n- Helvetica-Bold\n- Helvetica-BoldOblique\n- Helvetica-Oblique\n- Times-Roman\n- Times-Bold\n- Times-BoldItalic\n- Times-Italic\n- Courier\n- Courier-Bold\n- Courier-BoldOblique\n- Courier-Oblique\n- Symbol\n- ZapfDingbats\n- STSong-Light\n- MSung-Light\n- HYGothic-Medium\n- HeiseiMin-W3\n- HeiseiKakuGo-W5\n\u003c/details\u003e\n\nYou can also provide your own fonts in two ways:\n\n- Either by placing the font files (TTF, OTF, etc.) in a default folder where reportlab can find them (depending on the values in `reportlab.rl_config.TTFSearchpath`, e.g. on Linux it can be `/usr/share/fonts`, on Windows it can be `C:\\Windows\\Fonts`, on MacOS it can be `~/Library/Fonts`, etc.).\n- Or by providing a custom folder containing the font files using the `--custom-fonts-folder` option.\n\nIn either case, note that the `--text-font` option must be set to the exact name of the font (without the file extension). For example, if you have a font file named `MyFont-BoldItalic.ttf`, you should set `--text-font \"MyFont-BoldItalic\"`. There is no support for loading font family files at the moment. The recommended approach to provided custom fonts is to use TTF or OTF files.\n\n## Contributing\n\nContributions are always welcome, whether it is for bug fixes, new features or just to improve the documentation and code quality. Feel free to open an issue or a pull request.\n\n### Building the package\n\nThis project relies on [uv](https://github.com/astral-sh/uv).\n\n```\npip install uv\nmake install\n```\n\n### Checklist before opening a pull request\n\n- The code is formatted with `ruff`.\n- The tests pass.\n- The readme is updated if necessary (especially if the command line interface changes).\n\n## Authors\n\n[@bastienlc](https://github.com/bastienlc)\n\n## Version History\n\n- 1.0.0\n  - Add text watermark support.\n  - Add image watermark support.\n  - Add CLI.\n  - Add complex directories support.\n- 2.0.0\n  - Move tool to subcommand **grid**.\n  - Add **insert** command.\n- 2.1.0\n  - Add --unselectable and --save-as-image options.\n  - Fix bug with temporary files on Windows.\n- 2.1.2\n  - Fix missing Poppler dependancy.\n  - Add test and lint to CI.\n- 2.2.0\n  - Support PDFs with pages of different sizes.\n- 2.2.1\n  - Support line breaks in text watermark.\n- 2.2.2\n  - Support uppercase PDF extension.\n- 2.2.3\n  - Improve tooling and CI\n  - Add --dry-run option\n  - Add --verbose option\n  - Add parallel processing with --workers option\n- 3.0.0\n  - Add support for uvx execution\n  - Extend font support, enabling custom fonts and non-latin characters\n  - Migrate to dataclass-click, refactor codebase\n- 3.0.1\n  - Fix `TypeError: Cannot use PosixPath as a filename or file`\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- [dataclass-click](https://github.com/couling/dataclass-click): Great tool to create click command line interfaces from dataclasses.\n- [readme template](https://gist.github.com/DomPizzie/7a5ff55ffa9081f2de27c315f5018afc)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbastienlc%2Fpdf-watermark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbastienlc%2Fpdf-watermark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbastienlc%2Fpdf-watermark/lists"}