Skip to content
Get packs

Guide · Open source

How to use waifu2x: install, run and batch-convert images

Updated · written with AI from the project's own documentation and checked against our catalogue data

waifu2x is an open-source tool that enlarges images by two times and reduces noise, trained mainly on anime-style artwork with a photo model also included. This guide walks you through the install steps from the README, the main command-line modes, batch conversion of a folder and the hardware and software you need. By the end you will be able to run a 2x upscale or noise reduction on your own image.

waifu2xnagadomi/waifu2x · ★ 28.2k · MIT

Quick start

  1. 1Check hardware. Confirm you have an NVIDIA GPU and can install CUDA and Torch7.
  2. 2Install system packages. Install libsnappy-dev and libgraphicsmagick1-dev, as named in the README for Ubuntu.
  3. 3Clone the repo. Run git clone --depth 1 on the waifu2x repository.
  4. 4Install Lua modules. Enter the waifu2x folder and run ./install_lua_modules.sh.
  5. 5Validate. Run th waifu2x.lua to confirm the command-line tool works.
  6. 6Process an image. Run th waifu2x.lua with -m scale or -m noise and set -i and -o.

Check whether waifu2x fits your setup

waifu2x is built on Torch7 and NVIDIA CUDA, and the README lists an NVIDIA GPU as the hardware requirement. It is run from the terminal, either as a command-line program or as a local web app.

The README also notes that development has moved to a PyTorch successor project called nunif in 2023/02, so this repository should be treated as a legacy codebase.

  • You need an NVIDIA GPU.
  • You need to be comfortable running command-line tools.
  • You need Torch7 and NVIDIA CUDA installed before setup.
  • Windows users are pointed by the README to third-party tools such as waifu2x-caffe, waifu2x-ncnn-vulkan or waifu2x-converter-cpp.

Install the prerequisites and Torch7

The README's installation example was written for Ubuntu 16.04. It asks you to install CUDA, then a few system packages, then Torch7 following the official Torch getting-started guide. The README links separate threads for CUDA 9.x/8.x and CUDA 10.x Torch setups.

On Ubuntu the README names these packages: libsnappy-dev and libgraphicsmagick1-dev. It also lists a libssl1.0-dev package for the web server.

  • Install CUDA using the NVIDIA guide linked in the README.
  • Install libsnappy-dev and libgraphicsmagick1-dev with apt-get.
  • Install Torch7 from torch.ch.
  • The README notes that waifu2x needs GraphicsMagick linked with little-cms2; macOS/Homebrew users should check the linked issue.
sudo apt-get install libsnappy-dev sudo apt-get install libgraphicsmagick1-dev sudo apt-get install libssl1.0-dev # for web server

Clone the repository and install the Lua modules

Clone the repository with a shallow clone, then enter the folder and run the install script. The script installs the LuaRocks packages the tool needs: lua-csnappy, md5, uuid, csvigo and turbo.

  • Clone with --depth 1 to download only the latest commit.
  • Run the install script from inside the waifu2x folder.
git clone --depth 1 https://github.com/nagadomi/waifu2x.git cd waifu2x ./install_lua_modules.sh

Validate the command-line tool

Run the main script with th to confirm the setup works. The README uses this as its validation step. If you want to see every option, the README points you to the help flag.

If you have a cuDNN library, you can add -force_cudnn 1, which the README says is much faster than the default kernel. If you hit a GPU out-of-memory error, the README suggests lowering the work size with -crop_size, for example 128.

  • Use th waifu2x.lua -h to list options.
  • Add -force_cudnn 1 if cuDNN is installed.
  • Use -crop_size 128 if you run out of GPU memory.
th waifu2x.lua

Upscale or denoise a single image

The -m flag selects the mode. Use scale for a 2x upscale, noise for noise reduction, or noise_scale to do both. The -noise_level flag takes 0 to 3 for noise modes, and the README shows level 1 as its example. Set the input with -i and the output with -o.

  • -m scale: 2x upscaling only.
  • -m noise -noise_level 1: noise reduction (levels 0, 1, 2 and 3 are shown).
  • -m noise_scale -noise_level 1: noise reduction plus 2x upscaling.
th waifu2x.lua -m scale -i input_image.png -o output_image.png th waifu2x.lua -m noise -noise_level 1 -i input_image.png -o output_image.png th waifu2x.lua -m noise_scale -noise_level 1 -i input_image.png -o output_image.png

Convert a whole folder in one command

For batch work, the README shows building a list of image files with find, then passing that list to waifu2x with -l. The output name pattern accepts %s, which is replaced by the source file's basename, and %d, which is replaced by a sequence number. You can pad numbers, for example %06d.

For photos, add -model_dir models/photo to use the photo model instead of the default anime-style model.

  • Create image_list.txt with find, matching *.png and *.jpg.
  • Use -l to pass the list file.
  • Use %s for the original name and %d for a counter in the output path.
find /path/to/imagedir -name "*.png" -o -name "*.jpg" > image_list.txt th waifu2x.lua -m scale -l ./image_list.txt -o /path/to/outputdir/prefix_%d.png th waifu2x.lua -model_dir models/photo -m scale -i input_image.png -o output_image.png

Run the local web app instead

If you prefer a browser interface, the README gives a command to start the web application. It says the app is then viewable at a localhost address on port 8812. The README also links a cloud demo and an in-browser version, which are useful if you do not have an NVIDIA GPU.

  • Start the server with th web.lua.
  • Open http://localhost:8812/ in your browser.
th web.lua

What people use it for

  • Upscaling a small anime-style illustration to twice its size.
  • Reducing noise in a scanned or compressed anime image with -m noise.
  • Batch-converting a folder of PNG and JPG files with one list-driven command.
  • Running a local web app on your own machine for drag-and-drop style use.
  • Processing video frames: extracting PNGs with avconv, running waifu2x over the frame list, then re-encoding.

Frequently asked questions

Is waifu2x free to use?

waifu2x is released under the MIT licence, according to the repository summary. The README also notes that the 2D character image used in its references is licensed separately under CC BY-NC by piapro, so check that licence if you reuse that specific artwork.

Do I need an NVIDIA GPU to run waifu2x?

Yes, the README lists an NVIDIA GPU as the hardware requirement and CUDA as a platform dependency. Without an NVIDIA GPU, the README points to the cloud demo or the in-browser version instead.

Does waifu2x work on Windows?

The README does not give a Windows install path for this repository. It recommends third-party Windows tools instead: waifu2x-caffe, waifu2x-ncnn-vulkan or waifu2x-converter-cpp.

What are the alternatives to waifu2x?

The repository lists waifu2x-ncnn-vulkan, waifu2x-caffe, waifu2x-converter-cpp and nunif as comparable projects. The README says development has moved to nunif, the PyTorch successor.

Why does waifu2x run out of GPU memory?

The README suggests using the -crop_size option with a smaller value, such as 128, to lower memory use. Using cuDNN with -force_cudnn 1 is also recommended for speed.

Can I use waifu2x for photos?

Yes. The README says the project also supports photos and gives a command using -model_dir models/photo to select the photo model.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

waifu2x suits people with an NVIDIA GPU who are comfortable in the terminal and want to upscale anime-style art or batch-convert folders. If you want active development, a one-click desktop app or no GPU requirement, the README points you toward nunif or third-party tools instead.

Install options & downloads