{"record":{"id":"8636057d9f6351db","repo":"huggingface/transformers","slug":"you-need-to-install-hqq-in-order-to-use-kv-cache","errorCode":null,"errorMessage":"You need to install `HQQ` in order to use KV cache quantization with HQQ backend. Please install it via  with `pip install hqq`","messagePattern":"You need to install `HQQ` in order to use KV cache quantization with HQQ backend\\. Please install it via  with `pip install hqq`","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/transformers/cache_utils.py","lineNumber":847,"sourceCode":"class HQQQuantizedLayer(QuantizedLayer):\n    def __init__(\n        self,\n        nbits: int = 4,\n        axis_key: int = 0,\n        axis_value: int = 0,\n        q_group_size: int = 64,\n        residual_length: int = 128,\n    ):\n        super().__init__(\n            nbits=nbits,\n            axis_key=axis_key,\n            axis_value=axis_value,\n            q_group_size=q_group_size,\n            residual_length=residual_length,\n        )\n\n        if not is_hqq_available():\n            raise ImportError(\n                \"You need to install `HQQ` in order to use KV cache quantization with HQQ backend. \"\n                \"Please install it via  with `pip install hqq`\"\n            )\n\n        if self.nbits not in [1, 2, 3, 4, 8]:\n            raise ValueError(\n                f\"`nbits` for `HQQ` backend has to be one of [`1`, `2`, `3`, `4`, `8`] but got {self.nbits}\"\n            )\n\n        if self.axis_key not in [0, 1]:\n            raise ValueError(f\"`axis_key` for `HQQ` backend has to be one of [`0`, `1`] but got {self.axis_key}\")\n\n        if self.axis_value not in [0, 1]:\n            raise ValueError(f\"`axis_value` for `HQQ` backend has to be one of [`0`, `1`] but got {self.axis_value}\")\n\n        self.quantizer = HQQQuantizer\n\n    def _quantize(self, tensor, axis):","sourceCodeStart":829,"sourceCodeEnd":865,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/cache_utils.py#L829-L865","documentation":"ImportError raised in HqqQuantizedLayer.__init__ when KV-cache quantization is requested with backend='hqq' (HqqQuantizedCacheConfig) but the hqq package is missing. Like quanto, HQQ is an optional dependency imported lazily at cache-construction time, so the failure surfaces when DynamicCache.from_config(config) instantiates the quantized layers, not at transformers import.","triggerScenarios":"HqqQuantizedCacheConfig(nbits=8, axis_key=0, axis_value=0) used in an environment without hqq; deploying quantized-cache generation code to a slim production image; fresh venv missing quantization extras.","commonSituations":"CI/prod environments built from minimal requirements.txt; sharing notebooks that use HQQ KV quantization; uninstalling hqq after an experiment while configs still request it.","solutions":["pip install hqq","Guard at runtime with transformers.utils.import_utils.is_hqq_available() and fall back to DynamicCache","If you cannot add dependencies, use an unquantized cache or the quanto backend if optimum-quanto is present"],"exampleFix":"# before\nconfig = HqqQuantizedCacheConfig(nbits=8)\ncache = DynamicCache.from_config(config)  # ImportError\n\n# after\n# shell: pip install hqq\nconfig = HqqQuantizedCacheConfig(nbits=8)\ncache = DynamicCache.from_config(config)","handlingStrategy":"validation","validationCode":"from transformers.utils.import_utils import is_hqq_available\nif not is_hqq_available():\n    raise SystemExit('This script needs HQQ KV quantization: pip install hqq')","typeGuard":null,"tryCatchPattern":"try:\n    cache = DynamicCache.from_config(quant_config)\nexcept ImportError as e:\n    if 'hqq' in str(e):\n        cache = DynamicCache()  # unquantized fallback\n    else:\n        raise","preventionTips":["Add hqq to requirements for any pipeline using backend='hqq'","Gate with is_hqq_available() so the code degrades gracefully","Bake optional quantization deps into deployment images explicitly"],"tags":["dependencies","quantization","kv-cache","import-error"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}