Install & Compatibility
Where this runs
tested against v1.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 73.7s
py 3.11
✕ build_error
✓ 66.9s
py 3.12
✕ build_error
✓ 63.3s
py 3.13
✕ build_error
✓ 56.6s
py 3.9
✕ build_error
✕ timeout
4710MB installed
● package 4710MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ssim
✓ from pytorch_msssim import ssim
ms_ssim
✓ from pytorch_msssim import ms_ssim
SSIM
✓ from pytorch_msssim import SSIM
MS_SSIM
✓ from pytorch_msssim import MS_SSIM
pytorch_ssim
✓
✗ import pytorch_ssim
This refers to an older or different library/fork and is not the correct top-level package for `pytorch-msssim`.
This quickstart demonstrates how to calculate SSIM and MS-SSIM between two batches of images and how to use the SSIM and MS_SSIM classes as loss functions. Ensure your input tensors `X` and `Y` are of shape `(N, C, H, W)` and `data_range` is set correctly for your pixel value range.
import torch
from pytorch_msssim import ssim, ms_ssim, SSIM, MS_SSIM
# Create two dummy image tensors (batch_size, channels, height, width)
# Images are typically non-negative, e.g., 0-255 or 0-1
X = torch.rand(4, 3, 256, 256) * 255 # Example: batch of 4 RGB images, 0-255 range
Y = torch.rand(4, 3, 256, 256) * 255 # Another batch for comparison
# Calculate SSIM and MS-SSIM values (per image in batch)
# data_range should match the maximum possible pixel value (e.g., 255 for 0-255 images)
ssim_val = ssim(X, Y, data_range=255, size_average=False) # Returns (N,) tensor
ms_ssim_val = ms_ssim(X, Y, data_range=255, size_average=False) # Returns (N,) tensor
print(f"SSIM values: {ssim_val}")
print(f"MS-SSIM values: {ms_ssim_val}")
# Using SSIM/MS_SSIM as a loss function (returns scalar mean loss)
# For loss, set size_average=True and typically use 1 - score
ssim_loss_module = SSIM(data_range=255, size_average=True, channel=3)
ms_ssim_loss_module = MS_SSIM(data_range=255, size_average=True, channel=3)
ssim_loss = 1 - ssim_loss_module(X, Y) # A scalar tensor
ms_ssim_loss = 1 - ms_ssim_loss_module(X, Y) # A scalar tensor
print(f"SSIM Loss: {ssim_loss}")
print(f"MS-SSIM Loss: {ms_ssim_loss}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'msssim'
The user is attempting to import the library using 'msssim', but the correct package name for import is 'pytorch_msssim'.
fixfrom pytorch_msssim import ssim, ms_ssim
AssertionError: Expected 4D tensor as input, got 3D tensor.
The 'ssim' or 'ms_ssim' function requires input tensors to be 4-dimensional (batch, channels, height, width), but a tensor with fewer dimensions was provided.
fixReshape the input tensor to add a batch dimension, typically using `tensor.unsqueeze(0)`. For example: `ssim(img1.unsqueeze(0), img2.unsqueeze(0))`.
RuntimeError: Expected all tensors to be on the same device, but found at least two devices, cuda:0 and cpu!
The input tensors (img1 and img2) are located on different compute devices (e.g., one on CPU and one on GPU), which is not allowed for PyTorch operations.
fixMove both tensors to the same device using `.to(device)`. Example: `device = torch.device('cuda' if torch.cuda.is_available() else 'cpu'); img1 = img1.to(device); img2 = img2.to(device)`. Upgrade
Version history
1.0.0latest on PyPI · released May 25, 2023
Audit
Dependencies
torchrequiredCore PyTorch library for tensor operations and deep learning framework.