nagadomi/nunif: waifu2x in PyTorch plus iw3 2D to 3D conversion

What nunif actually contains, and who it is for

The README opens with a warning rather than a feature list: "For the time being, I will make incompatible changes." That single line should shape how you read everything else. nunif is described by its author as a playground, and the top level of the repository reflects that. It holds several unrelated tools rather than one product: waifu2x, iw3, stlizer, cliqa, plus training scripts and a windows_package directory. The topics list names super-resolution, VR and waifu2x, which matches the two projects most people arrive for.

The first audience is anyone who wants waifu2x as a PyTorch implementation with pretrained models rather than the original Torch code. The README states the repository contains that implementation and the models, and that the work started by porting the original waifu2x. It also notes the models cover photos, not just anime art, via GAN based models. If you already run the cloud or in-browser demos, this is the self-hosted path.

The second audience is narrower and more personal. The iw3 section begins: "I want to watch any 2D video as 3D video on my VR device, so I developed this very personal tool." That is not marketing copy, and it is honest about scope. iw3 converts any 2D image or video into side-by-side 3D. Around it sit two satellites: iw3-desktop, which turns your PC desktop into 3D and streams it over WiFi in realtime, and iw3-player, a self-hosted WebXR viewing environment for media already converted to 3D by iw3. The package list confirms the split, with timm and av==15.0.0 under an iw3 comment and fastapi, hypercorn, pysubs2 and pyopenssl under iw3-player.

Two further tools round out the repository and rarely get mentioned in the same breath. stlizer is described as a fast conservative video stabilizer. cliqa produces low-vision image quality scores that the README says are more consistent across different images, with two models, JPEGQuality and GrainNoiseLeve, and CLI tools to filter low quality images by threshold when building datasets. If your actual problem is dataset triage rather than upscaling, cliqa is the part of nunif you want.

How waifu2x and iw3 work under the hood

For waifu2x, the mechanism is a neural network inference pass. The repository carries the PyTorch implementation and the pretrained model weights, and hubconf.py at the top level exists so the project can be loaded through torch.hub. The README makes a specific claim about that route: if you load the repository with torch.hub.load for the waifu2x Python API, the GPL problem described in the licence notes does not exist because PyAV is not a dependent package. That is a real architectural distinction, not a footnote. The waifu2x path is a Python API and model inference; the video path drags in the media stack.

For iw3, the data flow is conversion first, viewing second. iw3 takes a 2D image or video and produces a side-by-side 3D image or video. That output is a file on disk, which is what makes the rest of the design possible. iw3-player then streams media that has been pre-converted to 3D from your PC to VR devices through a WebXR application. The word "pre-converted" matters: the player is a viewing environment, not a converter.

iw3-desktop breaks that pattern deliberately. It converts the PC desktop screen into 3D and streams it over WiFi, so any image, video or live content displayed on the PC can be watched as 3D in realtime. The trade-off is that realtime desktop capture is a different pipeline from file conversion, with different failure modes, and the README does not describe latency or quality behaviour for it.

Depth estimation is the piece that makes any of this work, and the dependency list is where you can see it. The requirements file groups pillow_heif, safetensors, einops, omegaconf and addict under comments naming depthpro and da3. Those are depth-model dependencies. Nothing in the README explains which depth model is chosen by default or how to switch, so treat the depth stage as the least documented part of the pipeline. If output looks wrong, depth estimation is the first place to look, and the README will not help you there.

Installing nunif and running a first conversion

The README splits installation into two paths. Windows users are pointed at the nunif windows package, with documentation in windows_package/docs/README.md and a Japanese translation alongside it. Developers are pointed at Python 3, PyTorch and requirements.txt, with platform files INSTALL-ubuntu.md, INSTALL-windows.md and INSTALL-macos.md. There are two extra files for hardware that needs them: INSTALL-xpu.md for Intel GPUs and INSTALL-cu126.md for older NVIDIA GPUs. The README also mentions extra_build for containers, packages and special hardware builds.

Start by installing the Python dependencies. The README states Python 3.10 or later, developed with 3.10, and says the project usually supports the latest version, specifying a version only when bugs or compatibility issues appear. PyTorch itself is not pinned in requirements.txt; the file instead tells you to install it from the PyTorch site, with torch, torchvision and torchtext commented out.

pip install -r requirements.txt

That installs the shared dependencies plus the iw3 and iw3-player groups, since the file is not split by tool. If you only want the waifu2x Python API, the README's torch.hub note suggests a lighter route that avoids PyAV entirely. One environment variable is worth setting before you run anything. The README states that if NUNIF_HOME is defined, downloaded pretrained models, configuration files, cache, temporary files and lock files are saved under it, and that a leading ~ is expanded to the home directory. Set it when the source directory is not writable, or when you are packaging.

The first run will download pretrained models into that location, which is why the variable exists. The README does not give a copy-paste command for a first iw3 conversion, so the honest step here is to open iw3/README.md, which the top-level README links, and follow the usage it documents there rather than guessing at flags. The same applies to waifu2x: the top-level README defers to waifu2x/README.md. What you should expect after a successful install is a model download on first use and, for iw3, an output file in side-by-side layout that iw3-player can stream.

Where nunif breaks down or is the wrong choice

The stability warning is the headline limitation. "For the time being, I will make incompatible changes" means command-line flags, config keys and Python APIs can move between commits. If you are building nunif into a pipeline that other people depend on, you are building on a moving target, and the README does not offer a stability policy, a deprecation window or a changelog that would let you plan upgrades. The release list is irregular rather than a version cadence: iw3_player_assets, python_dev_release and torchhub, the last of those from 2024-12-31.

Licensing is the second hard constraint, and it is a distribution problem rather than a usage problem. The README's licence notes state that if you distribute binary builds, it is possible that they will be GPL, because the PyAV (av) wheel package contains the GPL version of ffmpeg. It also states you can build PyAV with the LGPL version of ffmpeg instead, and that loading the repository with torch.hub.load for the waifu2x Python API avoids the issue because PyAV is not a dependency. The repository itself is MIT. Whether that combination is acceptable for your product is a question for your own legal review, not something the README resolves.

Documentation depth is uneven. The top-level README is a directory of links. waifu2x, iw3, iw3-player, stlizer and cliqa each have their own README, and iw3-desktop has a docs page, but the top-level file does not explain depth model selection, conversion quality settings, or what happens with unusual input like variable frame rate video or rotated phone footage. If your content is not a clean, standard video file, budget time for trial and error that the documentation will not shorten.

Finally, consider whether you need iw3 at all. If you want 3D on a VR headset and your source is already stereo, or your headset's own player handles the conversion, iw3 adds a conversion step, an output file and a streaming server for no benefit. The tool exists because the author wanted any 2D video watchable as 3D; if that is not your constraint, the surrounding pieces are dead weight.

How nunif differs from other super-resolution and depth tools

The most direct alternative for the waifu2x half is the original nagadomi/waifu2x repository, which the README names as the project nunif ported. The difference is the framework. The original is the reference implementation that defined the waifu2x model and the cloud and in-browser demos most people have used; nunif is a PyTorch reimplementation with pretrained models and a Python API reachable through torch.hub. If you want to read the canonical code or match historical behaviour exactly, the original is the source. If you want to call waifu2x from modern Python and run it on your own GPU, nunif is the more practical target, and the README's note that the torch.hub route avoids the PyAV dependency is a concrete reason to prefer it for API use.

For the 3D half, the honest comparison is not another repository but the category of tools that do one job. iw3 bundles conversion, a realtime desktop streaming mode and a self-hosted WebXR player in one repository, with shared dependencies and shared installation. A general-purpose depth estimation project or a standalone stereo conversion utility would give you one stage and expect you to wire the rest yourself. The trade-off runs both ways: nunif gives you an end-to-end path from a 2D file to something watchable in a headset, and in exchange you inherit a personal playground's documentation habits, its dependency set and its compatibility warning. If you only need depth maps, pulling in the whole repository for the depthpro and da3 dependencies is a poor fit.

Inside the repository there is also a genuine choice between tools. If your goal is filtering a dataset rather than upscaling or 3D, cliqa's JPEGQuality and GrainNoiseLeve models with threshold-based CLI filtering address that directly, and stlizer covers video stabilization. These are not alternatives to iw3; they are the reason a single clone can serve more than one job.

Maintenance, upgrade cost and licence handling

The repository is not archived, and the last push was on 2026-09-18, which is recent. The author is still working in it. That does not translate into API stability, because the README says the opposite in its second line, and the release history is not a semantic versioning cadence. Treat the commit history as the real changelog.

The upgrade cost sits in three places. First, the dependency set is broad and partly commented out, with PyTorch versions left to the user and av pinned at 15.0.0. A PyTorch upgrade can ripple through the whole install, and the README says the project usually supports the latest version but will pin when compatibility breaks. Second, model files live under NUNIF_HOME when it is set, so an upgrade that changes model expectations means re-downloading into that directory; keep it on a volume with space and back it up if model downloads are slow on your connection. Third, platform-specific installation files exist for a reason: INSTALL-xpu.md for Intel GPUs and INSTALL-cu126.md for older NVIDIA GPUs are separate documents, so a machine that needs one of them is not on the default path.

On licensing, the repository is MIT and the README states the GPL risk applies to distributed binary builds because of the PyAV wheel's ffmpeg. Three facts are worth holding together: you can build PyAV against LGPL ffmpeg, you can avoid PyAV entirely by using torch.hub.load for the waifu2x Python API, and the repository itself remains MIT. Which of those matters depends on whether you ship binaries and to whom. The README does not give a compliance procedure, and this is not legal advice; if you distribute builds, the question of what your ffmpeg build links against is one to put to your own counsel.

Editorial conclusion

Adopt nunif if you want a local, scriptable waifu2x model pipeline or you are willing to convert your own 2D library into side-by-side 3D for a VR headset and can tolerate a repository whose README says it will make incompatible changes. Do not adopt it if you need a stable public API, a hosted service with an SLA, or a GUI-first workflow on a machine with no PyTorch-capable GPU. Before you commit, read INSTALL-ubuntu.md, INSTALL-windows.md or INSTALL-macos.md for your platform, check whether your NVIDIA driver needs the INSTALL-cu126.md path, confirm your Python is 3.10 or later, and decide whether you can accept the GPL exposure that the README attributes to the PyAV wheel's bundled ffmpeg.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nagadomi/nunif on GitHub
4. README
5. Releases