Registry / ai-ml / pyiqa
library0.1.16pypypiunverified

pyiqa is a comprehensive PyTorch-based toolbox for Image Quality Assessment (IQA), offering reimplementations of numerous mainstream full-reference (FR) and no-reference (NR) metrics. It aims for GPU acceleration, often outperforming MATLAB counterparts, and provides calibrated results against official scripts where available. The library is actively maintained with frequent releases, adding new metrics, features, and bug fixes.

pip install pyiqa
INSTALL
IMPORT
SIG · PYIQA
P
pyiqa
ai-mlpythonv0.1.16
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.915 runs
dependency_conflict
glibc
py 3.103.915 runs
timeout
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

create_metric
from pyiqa import create_metric
list_models
from pyiqa import list_models
imread2tensor
from pyiqa import imread2tensor
from pyiqa.utils import imread2tensor
imread2tensor is directly exposed at the top level since recent versions for convenience.

This quickstart demonstrates how to list available metrics, create both Full-Reference (FR) and No-Reference (NR) IQA models, perform inference with dummy PyTorch tensors, and use a metric (like LPIPS) as a loss function with gradient propagation.

import pyiqa import torch # List all available metrics print("Available metrics:", pyiqa.list_models()) device = torch.device("cuda" if torch.cuda.is_available() else "cpu") # Create a Full-Reference (FR) metric (e.g., LPIPS) # For gradient propagation (e.g., as a loss function), set as_loss=True iqa_fr_metric = pyiqa.create_metric('lpips', device=device, as_loss=True) print(f"LPIPS metric ('lower_better'): {iqa_fr_metric.lower_better}") # Create a No-Reference (NR) metric (e.g., NIQE) iqa_nr_metric = pyiqa.create_metric('niqe', device=device) print(f"NIQE metric ('lower_better'): {iqa_nr_metric.lower_better}") # Dummy image tensors (Batch, Channels, Height, Width), RGB, 0~1 range img1 = torch.rand(1, 3, 256, 256).to(device) img2 = torch.rand(1, 3, 256, 256).to(device) # Compute FR score score_fr = iqa_fr_metric(img1, img2) print(f"LPIPS score: {score_fr.item():.4f}") # Compute NR score score_nr = iqa_nr_metric(img1) print(f"NIQE score: {score_nr.item():.4f}") # Example of using a metric as a loss function (requires as_loss=True) loss = score_fr # LPIPS is lower_better, directly usable as loss loss.backward() # Gradients will be computed print("Backward pass complete for LPIPS loss.")
Debug
Known issues
breakingModel weights for metrics were migrated to Hugging Face Hub (chaofengc/IQA-PyTorch-Weights) in v0.1.13. Older versions might try to download from previous locations which could be slower or unavailable.
fix
Upgrade to v0.1.13 or newer. For users in mainland China, set `export HF_ENDPOINT=https://hf-mirror.com` for faster downloads.
affects: <0.1.13
gotchaWhen using metrics as a loss function (`as_loss=True`), gradient propagation is enabled. However, not all metrics within pyiqa fully support backpropagation. Always verify a metric's support for backpropagation if used in a training loop.
fix
Consult `Model Cards` documentation for specific metrics or test for `backward()` compatibility.
affects: All versions
gotchaThe `set_random_seed` function was removed from the test process in v0.1.12. This change, along with a shift to uniform cropping for some metrics, may lead to slight differences in reported metric results compared to versions prior to v0.1.12.
fix
Be aware of potential minor result variations when comparing outputs across v0.1.12 and earlier versions. Ensure consistent evaluation protocols for reproducibility.
affects: <0.1.12
deprecatedA critical bug affecting `inception_score` calculation was present in version 0.1.14, leading to incorrect results.
fix
Upgrade to `v0.1.14.1` or newer, where this bug has been resolved.
affects: 0.1.14
gotchaThe FID (Fréchet Inception Distance) metric typically requires directories of images or precomputed statistics as input, not individual image files, when called from `create_metric`.
fix
Provide a path to a directory containing images for both target and reference inputs, or use precomputed statistics, when calculating FID. Refer to `clean-fid` documentation for more details.
affects: All versions
breakingA critical bug in NRQM calculation (stemming from SSIM function usage) was identified and resolved in `v0.1.6.beta`. This also affected the PI (Perceptual Index) metric. Calculations from previous versions may be inaccurate.
fix
Upgrade to `v0.1.6.beta` or newer to ensure correct NRQM and PI metric calculations. Recalculate any results obtained with affected older versions.
affects: <0.1.6.beta
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pyiqa'
The 'pyiqa' library is not installed in the current Python environment or the environment is not correctly activated.
fix
pip install pyiqa
AttributeError: module 'torch' has no attribute 'rfft'
This error occurs because the 'torch.rfft' function was deprecated and removed in newer versions of PyTorch, leading to incompatibility with `pyiqa` versions that still rely on it.
fix
Downgrade your PyTorch version to one that supports `rfft` (e.g., PyTorch < 1.8) or update `pyiqa` to a version compatible with your PyTorch installation. Check the `pyiqa` GitHub issues or documentation for specific PyTorch version requirements.
RuntimeError: CUDA out of memory
The GPU lacks sufficient memory to process the current operation, typically due to large image sizes, high batch sizes, or memory-intensive models.
fix
Reduce the batch size, decrease the input image resolution, free up GPU memory by deleting unused tensors and calling `torch.cuda.empty_cache()`, or use a GPU with more memory.
UserWarning: The input data range is not in [0, 1].
Input images are typically in the [0, 255] range, but pyiqa metrics generally expect input tensors normalized to [0, 1] by default, leading to incorrect results or unexpected behavior.
fix
Normalize your input image tensor to the [0, 1] range (e.g., `img_tensor = img_tensor / 255.0`) or explicitly set `data_range=255.0` when creating the metric: `iqa_metric = pyiqa.create_metric('lpips', data_range=255.0)`.
ModuleNotFoundError: No module named 'lpips'
The `lpips` library, which is an optional dependency for the LPIPS metric in pyiqa, was not installed in your environment.
fix
Install the missing dependency separately using `pip install lpips` or install `pyiqa` with all optional dependencies using `pip install pyiqa[all]`.
Upgrade
Version history
0.1.16latest on PyPI · released Jul 8, 2026
Audit
Dependencies
pythonrequiredRuntime environment
pytorchrequiredCore deep learning framework
torchvisionrequiredImage processing utilities
cudaoptionalGPU acceleration (optional)
numpyrequiredNumerical operations
opencv-python-headlessrequiredImage loading and processing
pillowrequiredImage loading and processing
scipyrequiredScientific computing
tqdmrequiredProgress bars
Agent activity
16 hits · last 30 days
node
12
OpenAI (training)
1
Resources
pyiqa — pip install pyiqa · libregistry