Image Preparer Troubleshooting

Troubleshooting

The AI setup fails

The Set up Best quality mode window shows what went wrong, and Try again carries on with whatever is still missing.

Message	What to do
Installing PyTorch failed - see the messages above	Read the last lines of the messages in the window. The usual causes are listed below this table.
Download failed: …	The model download was interrupted or blocked. Check your internet connection and click Try again; the download starts over (it's 288 MB).
The downloaded file didn't match the expected model (size/checksum)	The download was damaged on the way. Click Try again.
PyTorch can't be added to the packaged app	Only for a packaged .exe copy of the app: the AI mode needs the app installed from source (the launcher does this).

Common reasons PyTorch won't install:

• Not enough disk space. PyTorch is about 3 GB to download and takes more once unpacked. Free up space on the drive the app is installed on.
• The internet connection dropped, or a firewall or antivirus blocked download.pytorch.org. Click Try again.
• Antivirus locking files while they're unpacked. Try again, or pause the antivirus for the install.
• A Python version PyTorch doesn't support yet. If the messages say No matching distribution found for torch, install a current Python 3 version from python.org, then use ⋯ ▸ Repair in the launcher.

If it still won't install from inside the app, you can install it yourself. Open a command prompt in the app's folder and run:

.venv\Scripts\python -m pip install -r requirements-ai.txt

Then restart the app and pick Best quality (AI) again; it only downloads the model.

Best quality (AI) is very slow

About 1 second for a 2-megapixel picture and 6–8 seconds for 24 megapixels is normal on a recent NVIDIA card. If it's much slower, the model is probably running on the processor (CPU) instead of the graphics card. That happens when:

• There's no NVIDIA graphics card, or it's older than the GeForce 20-series. Use Balanced instead.
• The NVIDIA driver is too old for the CUDA 13 version of PyTorch the app installs. Update the driver from nvidia.com/drivers or the NVIDIA app, then restart the app.
• PyTorch was installed without GPU support (for example by hand without requirements-ai.txt). Install it again with the command above.

If you have more than one NVIDIA card, the app uses the newest one (and, among equals, the one with the most memory).

Couldn't process: … when using Best quality

• Out of memory (the message mentions CUDA out of memory): the graphics card is full. Close games, other AI apps and models loaded elsewhere, then open the picture again.
• The AI JPEG model isn't set up yet: pick Best quality (AI) again to run the setup, or switch to Balanced.

The app doesn't keep retrying the same settings after an error; move a slider or reopen the picture to try again.

A card says "Can't read this file", or Couldn't open: …

The file is damaged, isn't really the picture type its name says, or is in a format the app doesn't read (for example HEIC, AVIF, GIF or RAW camera files). Convert it to JPG, PNG or TIFF first. See File formats.

"No new images in what you dropped"

Everything you dropped is already in the list, or it held no supported pictures.

Some pictures failed to save

The message after Save all lists each one with the reason. Common causes: the output folder is read-only or on a full drive, or a file there is open in another program. Fix it and save again (the app asks before replacing the ones that did save).

The thumbnails don't change when I move the JPEG or Detail slider

That's on purpose: thumbnails only show color noise removal. Open a picture to see the other two. See Thumbnails only show color noise.

Running from source: "Python 3.10 or newer is required"

Launch RulZ Image Preparer.bat couldn't find Python. Install it from python.org (tick Add python.exe to PATH), or install the app through the launcher, which installs Python for you.

Auto crop problems

Problem	What to do
Installing the AI packages failed in Set up Auto crop	Read the last lines of the messages in the window. The causes are the same as for the Best quality setup; click Try again.
Download failed: … or …didn't match the expected file	The SAM 3.1 download (1.7 GB from huggingface.co) was interrupted or damaged. Check your internet connection and click Try again.
"Nothing found for …"	Try simpler or different words (face instead of the woman's face), or lower Confidence. Pictures where nothing is found are skipped when cropping.
It finds the wrong thing too	Raise Confidence, use more specific words, or pick Best match only.
The crop is too tight or too loose	Change Padding or Measured against; lower Mask threshold to make the found area bigger.
The first Preview takes a long time	Normal: the AI takes up to half a minute to load each time you start the app. If every Preview is slow, it's running on the processor instead of the graphics card; see Best quality (AI) is very slow, which has the same causes.
Couldn't check this picture: … mentioning CUDA out of memory	The graphics card is full. Close games, other AI apps and loaded models, then click Preview again. Auto crop needs about 2 GB.

To install the Auto crop parts yourself, open a command prompt in the app's folder and run these two commands, in this order:

.venv\Scripts\python -m pip install -r requirements-ai.txt torchvision

.venv\Scripts\python -m pip install -r requirements-crop.txt

Still stuck?

Open an issue with what you did, the exact message, and your graphics card.