Registry /
ai-ml / vector-quantize-pytorch
Install & Compatibility
Where this runs
tested against v1.31.1 · 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
✓ 77.5s
py 3.11
✕ build_error
✓ 70s
py 3.12
✕ build_error
✓ 60.2s
py 3.13
✕ build_error
✓ 57.5s
py 3.9
✕ build_error
✕ timeout
4813MB installed
● package 4813MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VectorQuantize
✓ from vector_quantize_pytorch import VectorQuantize
ResidualVQ
✓ from vector_quantize_pytorch import ResidualVQ
ResidualFSQ
✓ from vector_quantize_pytorch import ResidualFSQ
This quickstart demonstrates the basic usage of the `VectorQuantize` module. It initializes a VQ layer with a specified input dimension, codebook size, EMA decay, and commitment weight, then quantizes a random input tensor and returns the quantized output, codebook indices, and the commitment loss.
import torch
from vector_quantize_pytorch import VectorQuantize
# Initialize VectorQuantize
vq = VectorQuantize(
dim = 256, # input feature dimension
codebook_size = 512, # number of vectors in the codebook
decay = 0.8, # exponential moving average decay, lower means faster dictionary change
commitment_weight = 1. # weight on the commitment loss
)
# Example input tensor: (batch_size, sequence_length, dim)
x = torch.randn(1, 1024, 256)
# Perform quantization
quantized, indices, commit_loss = vq(x)
print(f"Original input shape: {x.shape}")
print(f"Quantized output shape: {quantized.shape}")
print(f"Indices shape: {indices.shape}")
print(f"Commitment loss: {commit_loss.item():.4f}")
Debug
Known issues
gotchaDead codebook entries are a common issue in Vector Quantization, where some codebook vectors are rarely or never used. This can lead to inefficient models. The library offers features like `orthogonal_reg_weight` to help mitigate this problem by encouraging codebook diversity.fixConsider setting `orthogonal_reg_weight` > 0 during `VectorQuantize` initialization. Monitor perplexity metrics to identify underutilized codes and adjust hyperparameters like `decay` and `commitment_weight`.
affects: All versions
gotchaThe vector quantization layer is non-differentiable, typically requiring a straight-through estimator (STE) for gradient flow. The standard STE might not fully capture the quantization operation's dynamics. The library includes the 'rotation trick' to potentially improve gradient quality through the VQ layer.fixEnable `rotation_trick=True` in the `VectorQuantize` constructor to allow for a more nuanced gradient transformation, which may lead to better training stability and performance.
affects: All versions
gotchaDistributed Data Parallel (DDP) training setups might encounter issues like hanging, especially in older versions or with specific configurations involving codebook updates (e.g., k-means clustering or EMA). While some DDP-related issues have been addressed, it's a known area of complexity.fixEnsure you are using the latest version of the library. If encountering DDP issues, verify the synchronization mechanisms of codebook updates (e.g., EMA) across devices and consult GitHub issues for specific distributed training guidance.
affects: <= 1.27.x (potential in earlier versions); check latest on DDP behavior
gotchaHyperparameters such as `decay` (for EMA codebook updates) and `commitment_weight` are critical for training stability and performance. Incorrect values can lead to unstable training, dead codes, or poor reconstruction quality.fixCareful tuning of `decay` (e.g., starting around 0.8-0.99) and `commitment_weight` (e.g., 0.25-1.0) is often required. Experiment with a range of values and monitor training metrics like loss, perplexity, and reconstruction quality.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'vector_quantize_pytorch'
The 'vector-quantize-pytorch' library is not installed in the Python environment.
fixInstall the library using pip: 'pip install vector-quantize-pytorch'.
ImportError: cannot import name 'VectorQuantize' from 'vector_quantize_pytorch'
The 'VectorQuantize' class is not present in the 'vector_quantize_pytorch' module.
fixVerify the correct class name and import statement by consulting the library's documentation.
TypeError: 'VectorQuantize' object is not callable
Attempting to call an instance of 'VectorQuantize' as a function, which is not supported.
fixEnsure that 'VectorQuantize' is instantiated correctly and its methods are called appropriately.
AttributeError: module 'vector_quantize_pytorch' has no attribute 'FSQ'
The 'FSQ' attribute does not exist in the 'vector_quantize_pytorch' module.
fixCheck the library's documentation for the correct attribute or class name.
ValueError: Input tensor must have at least 2 dimensions
The input tensor provided to the vector quantization function has fewer than 2 dimensions.
fixEnsure that the input tensor has the required number of dimensions as specified in the library's documentation.
Upgrade
Version history
1.31.1latest on PyPI · released Aug 2, 2026
Audit
Dependencies
torchrequiredCore deep learning framework dependency.
einopsoptionalOften used for tensor manipulation within complex models like ResidualFSQ; implicitly required by some modules.
einxoptionalUsed for tensor manipulation, particularly in advanced quantization modules like ResidualFSQ; implicitly required by some modules.