Upscayl User Guide

Upscayl is a free and open-source desktop application that enlarges and sharpens images using AI super-resolution models — turning small, blurry, or low-resolution pictures into larger, cleaner versions. It runs entirely on your own computer using your graphics card, so your images are never uploaded anywhere.

This guide walks you from installation through everyday use, every setting, and troubleshooting. It covers Upscayl v2.15.0 for Windows, macOS, and Linux.

Note

Upscayl does the heavy lifting on your GPU (graphics card) using the Vulkan graphics API. A reasonably modern dedicated GPU gives the best results, but Upscayl also runs on many integrated graphics chips.

Table of Contents

1. Quick Start
2. Installation
3. The Upscayl Window at a Glance
4. Upscaling Your First Image
5. Choosing an AI Model
6. Batch Upscaling a Whole Folder
7. Double Upscayl (Extra-Large Output)
8. Comparing Before and After
9. Settings Reference
10. Common Tasks (Recipes)
11. Where Files Are Saved
12. Privacy & Telemetry
13. Updating Upscayl
14. Troubleshooting
15. Frequently Asked Questions
16. Feature Reference Tables

1. Quick Start

1. Install Upscayl for your operating system (see Installation).
2. Open the app. A short onboarding walkthrough appears the first time — pick your language, theme, and update preference, then click Get Started.
3. In the left sidebar, Step 1 — Select Image: click the button and choose a png, jpg, jpeg, jfif, or webp file.
4. Step 2 — Select AI Model: leave it on Upscayl Standard for your first run.
5. Step 3 — Set Output Folder: by default the upscaled image is saved next to the original; click Set Output Folder to pick somewhere else.
6. Step 4 — Upscayl 🚀: click the button. A progress overlay shows percentage.
7. When it finishes, drag the comparison slider to inspect the result. The new file is in your chosen output folder.

Tip

Don't have a file handy? You can also drag-and-drop an image onto the window, or paste one from your clipboard with Ctrl+V (⌘+V on macOS). Pasting requires an output folder to be set first.

2. Installation

Upscayl ships as a normal desktop installer for each platform. Download the build that matches your operating system from the official releases page: github.com/upscayl/upscayl/releases.

Windows

Download the .exe installer (NSIS) or the portable .zip.

• The installer lets you choose the installation directory and installs for all users (it will request elevation/administrator rights).
• On first launch you may see a SmartScreen "Windows protected your PC" prompt. Click More info → Run anyway. (The Windows build is not yet code-signed — see the FAQ.)

Note

Windows requires a GPU with up-to-date Vulkan-capable drivers. Update your graphics drivers from your GPU vendor (NVIDIA / AMD / Intel) if upscaling fails.

macOS

Download the universal .dmg (works on both Apple Silicon and Intel Macs) and drag Upscayl into your Applications folder.

• Minimum supported version is macOS 12.0 (Monterey).
• A separate Mac App Store build also exists; the App Store version asks you to pick an output folder each time it launches, due to App Store sandbox rules.

Linux

Choose the package that fits your distribution:

• AppImage — make it executable (chmod +x) and run it; no installation needed.
• .deb — Debian/Ubuntu: sudo dpkg -i upscayl-*.deb
• .rpm — Fedora/openSUSE: sudo rpm -i upscayl-*.rpm
• Flatpak — available as org.upscayl.Upscayl.
• .zip — portable archive.

Important

Linux upscaling needs a working Vulkan stack (Mesa drivers for AMD/Intel, or the proprietary NVIDIA driver). If Upscayl reports "Invalid GPU", your Vulkan drivers are usually the culprit.

System requirements

Tip

Upscayl bundles seven AI models, so it works fully offline. An internet connection is never required to upscale an image.

3. The Upscayl Window at a Glance

The window is split into two parts:

• Left sidebar — two tabs:
  • Upscayl tab — the four numbered steps (select image, choose model, set output folder, upscale) plus the Batch Upscayl toggle and Double Upscayl checkbox.
  • Settings tab — every preference described in Settings Reference.
• Main area (right) — shows the instructions card when empty, your selected image, the progress overlay while working, and the before/after comparison when done.

On the far right edge is a small ⋯ (More Options) tab. Click it to slide out a drawer with the view-mode toggle, zoom control, a Reset Image button, and your personal upscaling stats.

Note

You can collapse the sidebar with the chevron button to give the image more room. On macOS the title bar is hidden/inset for a cleaner look.

4. Upscaling Your First Image

Upscayl's main workflow is the four numbered steps in the Upscayl tab.

Step 1 — Select an image

Click Select Image and pick a file, or use one of these shortcuts:

• Drag and drop an image anywhere onto the window.
• Double-click the empty main area to open the file picker.
• Paste an image from the clipboard with Ctrl+V / ⌘+V.

Accepted input formats: png, jpg, jpeg, jfif, and webp.

Warning

Clipboard paste accepts png, jpg, jpeg, and webp (not jfif), and only works once an output folder has been set. If no output folder is set, Upscayl shows a "Set Output Folder" message instead of pasting.

Step 2 — Select an AI model

Click the model button to open the model picker, which shows a before/after preview for each model. See Choosing an AI Model for guidance. The default is Upscayl Standard.

Step 3 — Set the output folder

By default, the upscaled image is saved in the same folder as the original. Click Set Output Folder to choose a different destination. If you want Upscayl to remember this folder between sessions, enable Save Output Folder in Settings.

Step 4 — Upscayl

Click Upscayl 🚀. A full-screen overlay shows a spinning logo and a live percentage. While it runs you can press STOP to cancel.

When complete:

• A system notification ("Image upscayled successfully!") appears (unless you turned notifications off).
• The main area switches to a before/after comparison (slider by default).

Tip

If you upscale the same image again with the same settings, Upscayl detects the existing output file and loads it instantly instead of re-processing — unless you enable Overwrite Previous Upscale.

5. Choosing an AI Model

Upscayl ships with seven built-in models. All of them are natively 4× models (they enlarge to four times the original width and height). You can request other scale factors with the scale slider (see Image Scale).

Caution

The Remacri, Ultramix, and Ultrasharp models are labelled Non-Commercial inside the app. Do not use their output in commercial projects. The Upscayl Standard, Lite, High Fidelity, and Digital Art models do not carry this restriction.

Adding your own models

You can import community or custom models. In Settings → Add Custom Models, click Select Folder and choose a folder named exactly models that contains only .param and .bin model file pairs. Imported models then appear at the bottom of the model picker.

Note

The folder must be named models, and it should contain only .param/.bin files. Upscayl rejects folders with the wrong name or no valid model files. A community collection lives at the Upscayl custom-models repository.

6. Batch Upscaling a Whole Folder

To process many images at once:

1. In the Upscayl tab, turn on the Batch Upscayl toggle at the top.
2. Step 1 now reads Select Folder — choose the folder containing your images.
3. Pick your model, scale, output folder, and any settings as usual.
4. Click Upscayl 🚀.

Upscayl creates a new subfolder inside your output location named after your settings, for example:

upscayl_png_upscayl-standard-4x_4x

The pattern is upscayl_<format>_<model>_<scale>x (or ..._<width>px if you use a custom output width). When finished, an Open Upscayled Folder button appears so you can jump straight to the results.

Important

Put only images (png, jpg, jpeg, webp) in the source folder. Other files (including hidden system files like macOS .DS_Store/AppleDouble sidecars) can cause "Couldn't read the image" errors during a batch run.

Warning

Batch mode is not recursive — it processes images in the selected folder only, not in nested subfolders.

7. Double Upscayl (Extra-Large Output)

Double Upscayl runs the AI model on your image twice in a row — feeding the first result back in for a second pass. This produces a much larger image. With a 4× model, a double pass yields roughly 16× the original dimensions while still using AI on both passes.

To use it:

1. Make sure Batch Upscayl is off (Double Upscayl is for single images).
2. Tick the Double Upscayl checkbox under the model selector.
3. Upscale as normal.

The progress overlay shows which pass is running ("Pass 1", "Pass 2").

Caution

Double Upscayl multiplies both the time and the memory needed. On large source images or modest hardware it can be very slow or run out of GPU memory. Start with smaller images to gauge how your machine handles it.

8. Comparing Before and After

Once an image finishes, the main area shows a comparison view. Open the ⋯ More Options drawer on the right edge to switch modes and adjust zoom.

In Slider view, the Zoom Amount control (in the More Options drawer) magnifies on hover from 100% up to 1000%, so you can inspect fine detail.

The drawer also shows your stats: total upscayls, batch upscayls, single-image upscayls, double upscayls, average time, last duration, and when you last used the app. Use Reset Image to clear the current image and start over.

9. Settings Reference

Open the Settings tab in the sidebar. Settings are saved automatically and persist between sessions.

Image Scale (1–16×)

A slider that sets how many times larger the output should be (default 4×).

Important

The bundled models are AI-trained at 4×. Setting the slider above 4× (with one exception) only resizes the AI's 4× result with ordinary scaling — it does not add extra AI detail. The single exception is 16×, which is reached by enabling Double Upscayl (two genuine AI passes).

Values above 5× may cause performance issues on some devices; Upscayl shows a warning at high scales.

Custom Output Width

Instead of a multiplier, set an exact output width in pixels. The height is adjusted automatically to keep the aspect ratio. Enabling this overrides the Image Scale setting.

Note

The in-app note states that changing this option requires a restart to take full effect.

Save Image As (output format)

Choose the output file format: PNG, JPG, or WEBP.

• PNG — lossless, largest files, best quality.
• JPG — lossy, smaller files, best for photos and metadata compatibility.
• WEBP — lossy, modern, good size-to-quality balance.

This choice is remembered between sessions.

Image Compression (0–100)

A slider controlling output compression.

• PNG: compression is lossless — higher values shrink files only modestly and may slow processing.
• JPG / WEBP: compression is lossy — higher values mean smaller files and lower quality.

Copy Image Metadata

Keeps the original image's EXIF metadata (camera info, etc.) in the upscaled image.

Tip

Metadata is most reliably preserved when saving as JPG. If you enable this with a non-JPG format, Upscayl offers to switch to JPG and warns that some systems may not show metadata in other formats.

GPU ID

Selects which GPU to use, by numeric ID, if your system has more than one. Leave it empty to let Upscayl pick automatically. On Windows, enabling your system's "performance mode" / high-performance GPU can give better results.

Custom Tile Size

Sets the tile size used to split an image into chunks during processing. 0 means Auto. Adjusting this can help process images faster or work around memory limits.

Tip

If you hit out-of-memory errors on large images, try a smaller tile size. If you see tiling artifacts (visible seams), try a larger tile size or 0 (Auto).

TTA Mode

Test-Time Augmentation improves quality (e.g. fewer artifacts) by processing the image in multiple orientations and combining the results.

Caution

TTA Mode increases processing time by roughly 8×. Use it only when you need the extra quality.

Overwrite Previous Upscale

When on, Upscayl re-processes an image even if a matching output file already exists. When off (default), it loads the existing result instantly to save time.

Save Output Folder

When on, Upscayl remembers your chosen output folder between sessions instead of defaulting to each image's own folder.

Turn Off Notifications

Disables the system pop-up notifications Upscayl shows on success or failure.

Auto Update Upscayl

When on (default), Upscayl checks for new versions on launch and prompts you to install them. (Not applicable to the Mac App Store build, which updates through the store.)

Help Improve Upscayl

Controls anonymous usage telemetry. When on, Upscayl sends anonymous interaction data to help improve the app. Turn it off to opt out completely. See Privacy & Telemetry.

Upscayl Theme

Pick from 30 built-in color themes (the default is the custom upscayl dark theme). Options include light, dark, cupcake, synthwave, dracula, retro, cyberpunk, and many more.

Upscayl Language

Switch the interface language. 17 languages are selectable, including English, Arabic, German, Spanish, French, Hungarian, Indonesian, Japanese, Polish, Portuguese (Portugal and Brazil), Russian, Turkish, Ukrainian, Valencian Catalan, Vietnamese, and Simplified Chinese.

Reset Upscayl

Clears all saved settings and preferences and returns Upscayl to defaults. You will be asked to restart the app afterward.

Warning

Reset Upscayl erases all your preferences (theme, language, output folder, model choice, toggles, and stats). It cannot be undone.

System Info & Logs

The Settings tab also shows your System Info (platform, CPU, GPU, etc.) and a live Logs panel. The Copy Logs 📋 button copies the full log to your clipboard — handy when asking for help. A Get Help button opens the documentation.

10. Common Tasks (Recipes)

Make a photo print-ready (bigger, keep camera data):

1. Settings → Save Image As: JPG.
2. Settings → Copy Image Metadata: on.
3. Model: High Fidelity or Upscayl Standard, scale 4×.
4. Upscale.

Upscale anime / illustrations:

1. Model: Digital Art.
2. Scale 4×, format PNG for crisp edges.

Process a folder of product photos:

1. Turn on Batch Upscayl, select the folder.
2. Model Upscayl Standard, format WEBP for small web-ready files.
3. Set an output folder and upscale.

Get the absolute largest result from one image:

1. Single-image mode, tick Double Upscayl.
2. Use a 4× model for an effective ~16× result.
3. Be patient — this is slow and memory-heavy.

Squeeze the cleanest possible result, time no object:

1. Enable TTA Mode.
2. Use Upscayl Standard or High Fidelity at 4×.
3. Accept ~8× longer processing.

11. Where Files Are Saved

Single image (and Double Upscayl): the output file is written to your chosen output folder, named:

<originalname>_upscayl_<scale>x_<model>.<format>

For example, photo.jpg upscaled 4× with Upscayl Standard as PNG becomes:

photo_upscayl_4x_upscayl-standard-4x.png

If you used a custom output width, the <scale>x part becomes <width>px instead.

Batch: results go into a new subfolder of your output location named upscayl_<format>_<model>_<scale>x.

Warning

On Windows, output file paths longer than 255 characters can fail. If you see a "filename too long" error, shorten the filename or choose a shorter output path.

12. Privacy & Telemetry

Upscayl processes all images locally on your computer — your pictures are never uploaded to any server during upscaling.

Upscayl does make a few optional network connections:

Note

The analytics are anonymous and capture interactions, not your images. You can opt out entirely with the Help Improve Upscayl toggle.

13. Updating Upscayl

With Auto Update Upscayl enabled (the default), Upscayl checks for updates each time it starts. When a new version is available it downloads in the background, then shows a dialog:

• Install update — restarts and applies the update.
• No Thanks — keeps your current version.
• Check Release Notes — opens the release page in your browser.

You can always download the latest version manually from the releases page.

14. Troubleshooting

Troubleshooting entries below use the exact messages Upscayl shows. To gather details for a bug report, open Settings → Logs → Copy Logs 📋.

Error: Invalid GPU / "GPU Error"

Cause: Upscayl's AI engine can't access a working Vulkan GPU, or the selected GPU ID is wrong.

Solution:

• Update your graphics drivers to the latest version.
• Clear the GPU ID field (leave it empty for auto-detect), or try a different ID if you have multiple GPUs.
• On Linux, confirm your Vulkan stack is installed and working.

Prevention: Keep GPU drivers current; leave GPU ID empty unless you specifically need a particular card.

Error: "Read/Write Error" — Make sure that the path is correct and you have proper read/write permissions

Cause: Upscayl can't read the source image or write to the output folder, often due to permissions or special characters in the path.

Solution:

• Choose an output folder you own and can write to.
• Avoid unusual characters in file or folder names (see the % note below).
• On macOS/Linux, check folder permissions.

Error: filename contains % and Upscayl hangs at "Doing the Upscayl magic…"

Cause: A percent sign (and similar %VAR% patterns on Windows) in the filename can cause the upscale to stall. This is a known issue.

Solution: Rename the image to remove % (and other special characters) before upscaling.

Error: "The tile size is wrong"

Cause: The Custom Tile Size value is invalid for your image/GPU.

Solution: Set Custom Tile Size back to 0 (Auto), or try a smaller value.

Error: out of memory on large images (e.g. vkAllocateMemory failed)

Cause: The image (or scale) is too large for your GPU's memory. Very common with big images, high scales, or Double Upscayl.

Solution:

• Lower the Image Scale.
• Set a smaller Custom Tile Size (this reduces memory per chunk).
• Avoid Double Upscayl on very large images.
• Close other GPU-heavy applications.

Black or blank output image

Cause: Typically a GPU/driver issue or an unsupported format conversion path.

Solution:

• Update GPU drivers.
• Try a different output format (e.g. PNG instead of JPG).
• Try a smaller scale or a different model.

"Couldn't read the image" during batch

Cause: The source folder contains a non-image or hidden system file.

Solution: Remove everything except png/jpg/jpeg/webp files from the folder (including hidden files like .DS_Store), then run the batch again.

Filename too long (Windows)

Cause: The output path exceeds 255 characters.

Solution: Shorten the source filename or pick a shorter output folder.

Error: "Exception Error" — the upscayl binary failed to execute

Cause: The internal upscaling engine failed to run.

Solution: Open the Logs panel for details, update Upscayl and your GPU drivers, and if it persists, report the issue with your copied logs on GitHub.

15. Frequently Asked Questions

Q: Does Upscayl need an internet connection? No. All upscaling happens locally with bundled models. Internet is used only for optional update checks, the news banner, and (if enabled) anonymous analytics.

Q: Are my images uploaded anywhere? No. Images are processed entirely on your own machine.

Q: What image formats can I open? png, jpg, jpeg, jfif, and webp. (Clipboard paste supports all of these except jfif.)

Q: What formats can I save to? PNG, JPG, or WEBP.

Q: Can Upscayl upscale videos or GIFs? Not in this version (v2.15.0). Upscayl works on still images only. Video upscaling is a frequently requested feature but is not available in the desktop app yet.

Q: Is there a command-line version? The desktop app itself is GUI-only; it drives an internal upscaling engine for you. A separate command-line project exists outside this application but is not part of it.

Q: What does "Double Upscayl" actually do? It runs the AI model twice, feeding the first result back in. With a 4× model this yields roughly a 16× enlargement using AI on both passes.

Q: Why does setting the scale above 4× not look much sharper? The models are trained at 4×. Above 4× (except 16× via Double Upscayl), Upscayl just resizes the 4× result with ordinary scaling — no extra AI detail is added.

Q: Can I use the results commercially? The Standard, Lite, High Fidelity, and Digital Art models are unrestricted. The Remacri, Ultramix, and Ultrasharp models are marked non-commercial — don't use their output in commercial work.

Q: How do I add more models? Settings → Add Custom Models → select a folder named models containing .param and .bin files. See the custom-models repo.

Q: Where did my upscaled image go? By default, next to the original (single image) or into an upscayl_… subfolder of your output location (batch). Enable Save Output Folder to keep a fixed destination.

Q: How do I make Upscayl faster? Use Upscayl Lite, keep the scale at 4× or lower, avoid TTA Mode and Double Upscayl, and ensure a capable GPU with current drivers. Adjusting Custom Tile Size can help too.

Q: How do I turn off the pop-up notifications? Settings → Turn Off Notifications.

Q: How do I reset everything? Settings → Reset Upscayl, then restart. This clears all settings and stats.

Q: Can I change the look of the app? Yes — Settings → Upscayl Theme offers 30 color themes.

Q: My language isn't listed. 17 languages are currently selectable in the app. If yours isn't there, the project welcomes translation contributions on GitHub.

Q: How do I get help or report a bug? Use Settings → Get Help for documentation, copy your logs with Copy Logs 📋, and open an issue at github.com/upscayl/upscayl/issues.

16. Feature Reference Tables

Input & output formats

Bundled AI models

All settings at a glance

Keyboard & mouse shortcuts