Install & Compatibility
Where this runs
tested against v0.8.2 · 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.9s
py 3.11
✕ build_error
✓ 69.4s
py 3.12
✕ build_error
✓ 63s
py 3.13
✕ build_error
✓ 60.7s
py 3.9
✕ build_error
✕ timeout
4787MB installed
● package 4787MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
kornia
✓ import kornia as K
Standard alias for Kornia.
AugmentationSequential
✓ from kornia.augmentation import AugmentationSequential
✗ from kornia import AugmentationSequential
Most functionalities are within Kornia's submodules, like `augmentation`.
rgb_to_grayscale
✓ from kornia.color import rgb_to_grayscale
✗ from kornia import rgb_to_grayscale
Color conversions are found in the `kornia.color` submodule.
This quickstart demonstrates basic Kornia usage: creating a dummy image tensor, converting it to grayscale, and applying a Gaussian blur filter. It highlights common imports and tensor operations. For actual image loading, libraries like Pillow or OpenCV are typically used, followed by `K.image_to_tensor`.
import torch
import kornia as K
import numpy as np
from PIL import Image
import matplotlib.pyplot as plt
# Simulate loading an image or create a dummy tensor
# In a real scenario, replace this with actual image loading (e.g., with Pillow/OpenCV)
# and conversion using K.image_to_tensor.
# Example with a dummy tensor:
image_tensor = torch.rand(1, 3, 256, 256, dtype=torch.float32)
# Convert image to grayscale
grayscale_tensor = K.color.rgb_to_grayscale(image_tensor)
# Apply a Gaussian blur
blurred_tensor = K.filters.gaussian_blur2d(grayscale_tensor, kernel_size=(7, 7), sigma=(1.5, 1.5))
print(f"Original image shape: {image_tensor.shape}")
print(f"Grayscale image shape: {grayscale_tensor.shape}")
print(f"Blurred image shape: {blurred_tensor.shape}")
# --- Optional: Visualization (requires matplotlib and numpy) ---
# Convert tensors to NumPy arrays for display
# You might need to detach from GPU and move to CPU if applicable:
# grayscale_np = K.tensor_to_image(grayscale_tensor.detach().cpu())
# blurred_np = K.tensor_to_image(blurred_tensor.detach().cpu())
# fig, axs = plt.subplots(1, 2, figsize=(10, 5))
# axs[0].imshow(grayscale_np)
# axs[0].set_title('Grayscale Image')
# axs[0].axis('off')
# axs[1].imshow(blurred_np)
# axs[1].set_title('Blurred Image')
# axs[1].axis('off')
# plt.show()
Debug
Known issues
gotchaKornia's keypoint and bounding box operations, while using float coordinates, often assume an underlying pixel-center (index-based) convention (e.g., pixel (3,4) center is at (3.5, 4.5)). This can lead to slight inaccuracies or off-by-one errors if precise sub-pixel float coordinates are expected, potentially affecting model accuracy or geometric transformations.fixRefer to Kornia's documentation on coordinate conventions for keypoints and bounding boxes. Be mindful of how your input coordinates align with Kornia's assumed convention, especially when integrating with other libraries or performing precise geometric tasks.
affects: All versions
gotchaWhile `pip install kornia` is the primary installation, functionalities like `kornia.io.load_image` (for robust image I/O) internally rely on `kornia_rs`. If you encounter errors related to image loading, ensure `kornia_rs` is also installed (e.g., `pip install kornia kornia_rs`).fixExplicitly install `kornia_rs`: `pip install kornia_rs`.
affects: All versions
gotchaWhen using `kornia.augmentation` for differentiable data augmentation, distinguish between `torch.nn.Parameter` (for parameters that should be optimized/differentiated) and `torch.Tensor` (for static parameters). Incorrect usage can lead to unintended optimization behavior in meta-learning or differentiable augmentation pipelines.fixCarefully define your augmentation parameters; use `nn.Parameter` for trainable parameters and regular `torch.Tensor` for fixed ones. Consult the differentiable data augmentation tutorials for examples.
affects: All versions
breakingKornia continuously evolves. Older versions of PyTorch might not be compatible with the latest Kornia releases. Specifically, Kornia 0.8.x requires PyTorch >=2.0.0.fixEnsure your PyTorch version is up-to-date and compatible with your Kornia version. For Kornia 0.8.x, ensure `torch>=2.0.0` is installed. Check the official Kornia documentation or `pyproject.toml` for precise `torch` version requirements for your specific Kornia version.
affects: <0.8.0 with PyTorch <2.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'kornia'
The kornia library has not been installed in your current Python environment, or the environment is not correctly configured.
fixInstall kornia using pip: `pip install kornia` or, if using a specific version, `pip install kornia==0.8.2`. If using Conda, create and activate an environment, then `pip install kornia`.
AttributeError: module 'kornia' has no attribute '...' (e.g., 'get_perspective_transform', 'resize', 'rgb_to_grayscale', 'HomographyWarper')
This error typically indicates that you are trying to use a function or class that has been renamed, moved, or removed in a different version of Kornia than the one your code expects. This is common in actively developed libraries like Kornia due to API changes.
fixCheck the official Kornia documentation for version 0.8.2 (or your installed version) to find the correct module path or the updated name of the function/class. You may need to adjust your import statements or the function call directly. For example, `kornia.augmentation.functional` was removed in older versions and functions are now often directly under `kornia.augmentation`.
RuntimeError: Expected all tensors to be on the same device, but found at least two devices, cuda:0 and cpu!
This PyTorch-related error occurs when operations are attempted between tensors that reside on different devices (e.g., one on CPU and another on GPU). Some Kornia functions might implicitly create tensors on the CPU or not correctly infer the device of input tensors, leading to mismatches.
fixEnsure all tensors involved in a Kornia operation are explicitly moved to the same device using `.to(device)` before the operation. For example, if your input is on `cuda:0`, ensure any other tensors, models, or parameters involved are also on `cuda:0`. Define `device = 'cuda:0' if torch.cuda.is_available() else 'cpu'` and apply `.to(device)` to all relevant tensors and models.
Upgrade
Version history
0.8.3latest on PyPI · released May 19, 2026
Audit
Dependencies
torchrequiredKornia is built on top of PyTorch, requiring a compatible PyTorch installation (>=2.0.0).
kornia_rsoptionalRequired for some advanced I/O functionalities, such as `kornia.io.load_image`, which uses Rust-based low-level computer vision operations.
packagingoptionalDependency for certain internal packaging utilities.