remove-ai-watermarks/docs/installation.md

Installation

Python 3.10.1 or newer is required.

Core install

The core package provides:

• provenance inspection;
• visible watermark removal with OpenCV;
• manual region erasing with OpenCV;
• AI metadata inspection and removal.

Install it as an isolated command with uv:

uv tool install remove-ai-watermarks

Or with pipx:

pipx install remove-ai-watermarks

You can also install the Homebrew package on macOS or Linux:

brew install wiltodelta/tap/remove-ai-watermarks

Invisible watermark removal

Diffusion based removal needs the gpu extra:

uv tool install --force "remove-ai-watermarks[gpu]"

The code supports CUDA, XPU, MPS, and CPU devices. A GPU is recommended because CPU inference is slow.

For the CUDA only Qwen Image plus Z-Image profile:

uv tool install --force "remove-ai-watermarks[qwen-zimage]"

The qwen-zimage extra includes the normal gpu dependencies.

Optional features

Install only what you need:

Extra	Adds
migan	MI-GAN ONNX fill backend
lama	big-LaMa ONNX fill backend
detect	Open DWT-DCT watermark decoder used by identify
trustmark	Adobe TrustMark decoder
esrgan	Real-ESRGAN upscaling before diffusion
qwen-zimage	CUDA only Qwen Image plus Z-Image pipeline

Example:

uv tool install --force "remove-ai-watermarks[migan,detect]"

Some optional models download their weights on first use.

Install from the repository

git clone https://github.com/wiltodelta/remove-ai-watermarks.git
cd remove-ai-watermarks
uv sync --frozen

Add the feature groups required for your work:

uv sync --frozen --extra dev
uv sync --frozen --extra dev --extra gpu

Run commands from the repository root:

uv run remove-ai-watermarks --help

Development setup

Install development dependencies:

uv sync --frozen --extra dev

Run the complete project gate:

bash maintain.sh

The script runs dependency checks, linting, formatting checks, type checking, and the test suite.

Hugging Face authentication

Pass a Hugging Face token directly when the selected model or account requires one:

remove-ai-watermarks invisible image.png --hf-token "$HF_TOKEN"

The CLI also loads HF_TOKEN from the environment and from a local .env file. The same name is documented in .env.example.

Troubleshooting

The first model run is slow

Diffusion and learned fill backends may download model weights on first use. Later runs reuse their caches.

The command skips invisible removal

The normal behavior is to skip diffusion when no supported local signal is found. A missing signal does not prove that the image is clean. If you know the image came from a relevant generator, use --force.

If the CLI reports that diffusion dependencies are unavailable, install the gpu extra.