WatermarkRemover-AI/docs/windows-portable.md

Windows portable application

The portable package contains a versioned WatermarkRemover-AI.exe, CPython 3.13.15, the application dependencies, Qt WebEngine, and the complete offline interface. No system Python, Git, administrator access or WebView2 installation is needed. Extract the whole archive to a writable directory before opening the EXE; do not launch it from inside the archive.

First launch

1. Choose the CPU package for broad hardware compatibility, or the CUDA 12.6 package for a compatible NVIDIA GPU/driver. See device guidance.
2. Extract the package and open WatermarkRemover-AI.exe.
3. Open Models, then choose Download / Retry. The application checks its pinned LaMA and Florence-2 files, downloads missing/damaged files and shows progress. Model data is about 1.8 GB; allow additional disk space for the application and temporary transfers.
4. After ready appears, choose input and output paths and process a file. Detection Preview uses the same prepared models.

A connection failure is shown in the Models panel. Fix the connection or free disk space and use Download / Retry again. Completed verified files are reused. Partial Florence-2 transfers resume when the server supports byte ranges; LaMA restarts an interrupted transfer. No downloaded file is accepted before its pinned size and SHA-256 match. Neither application updates nor arbitrary scripts are fetched through this model downloader.

The UI, translations, themes and fonts work without internet. Processing uses prepared local models. First model preparation requires access to GitHub and Hugging Face, or a preseeded cache. See offline cache instructions. The Florence-2 manifest and pinned snapshot revision are in models/florence.json. Source installers remember the selected Florence mirror for later desktop retries. An explicit HF_ENDPOINT takes precedence over the saved model-endpoint.json in the application data directory; only HTTPS base URLs without credentials, query strings or fragments are accepted. A mirror never changes the pinned checksums. LaMA still uses its separate GitHub source. To persist a different Florence endpoint:

python -m model_assets --florence-only --endpoint https://huggingface.co

FFmpeg is still optional and must be available on PATH to preserve video audio. The UI reports its availability. The package does not silently install a system codec or driver. CUDA packages do not certify every NVIDIA card or older driver; MPS is not a Windows feature and is outside the current LaMA device contract.

Portable state and upgrades

data/ beside the executable stores settings, logs and default model caches. Explicit TORCH_HOME, HF_HOME or Hugging Face cache variables still take precedence. Keep the data directory when moving the portable application. For an upgrade, extract into a new directory, close the old application, then copy data/ into the new directory. Keep the previous version until the new one works. Do not mix dependency folders from different versions or CPU/CUDA packages.

Source installations use the user's application data directory for new settings and logs, and read an existing project ui.yml when no new settings file exists. Existing theme and language choices are retained.

Diagnostics

• data/desktop.log records windowed-launch errors. Inspect it before sharing; logs may contain local paths and processing details.
• build-info.json identifies version, backend, Python artifact and source commit.
• installed-packages.txt records the exact package versions included in the build.
• Launch WatermarkRemover-AI.exe --check to exercise the real local page and JavaScript/Python bridge without downloading production models. This is a UI installation check, not proof of GPU or model inference.
• For CLI usage, run python/python.exe remwm.py INPUT OUTPUT from the extracted directory. Keep cache variables consistent with your GUI cache; in a shell set TORCH_HOME to data/models/torch and HF_HOME to data/models/huggingface.

Building and release checks

On Windows, from a clean checkout with a working build Python/pip:

python scripts/build_windows.py --output dist --cache build-downloads --backend cpu
python scripts/build_windows.py --output dist --cache build-downloads --backend cu126

The builder verifies the embedded Python archive, uses the explicit Torch index, checks dependency resolution and imports, compiles the native launcher and emits versioned ZIP/SHA-256 files. Runtime DLLs and dependencies' license files remain separate in the package. Python entry-point wrappers containing build-machine paths are excluded; use python.exe -m pip for intentional package maintenance. Never run installation commands into a release candidate after recording its validation evidence. Build diagnostics are not a promise of byte-for-byte reproducible archives: preserve the emitted package inventory and checksum.

For application-only rebuilds, --refresh-app requires matching Python, backend, Torch, torchvision, and pip versions and dependency manifests from the previous build. It replaces application directories so removed files cannot remain. Runtime changes or old build metadata require a fresh output directory. User data and the embedded runtime are preserved during an application-only refresh.

CI builds the CPU executable and exercises the actual offline desktop page. The Windows portable workflow builds both CPU/CUDA artifacts on a version tag or manual dispatch, without automatically publishing a release. Before publishing, validate the extracted archive from another directory, first model download, connection failure/retry, preview, processing, cancellation and error reporting. Real model/GPU runs stay in a trusted environment outside pull-request CI.