Install & Compatibility
Where this runs
tested against v0.44.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
4/8 runs
py 3.11
✕ build_error
4/8 runs
py 3.12
✕ build_error
4/8 runs
py 3.13
✕ build_error
4/8 runs
py 3.9
✕ build_error
4/8 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
modelopt
✓ import modelopt
✗ from diffusers import NVIDIAModelOptConfig
modelopt_recipes
✓ import modelopt_recipes
This quickstart demonstrates how to load a Hugging Face model and apply FP8 quantization using `NVIDIAModelOptConfig`. It shows the integration of Model Optimizer with popular deep learning frameworks and libraries like Hugging Face Diffusers to prepare models for efficient deployment.
import torch
from diffusers import AutoModel, NVIDIAModelOptConfig
from modelopt.torch.opt import enable_huggingface_checkpointing
import os # Required for os.environ.get if needed for token, though not direct in this example
# Enable checkpointing for Hugging Face models
enable_huggingface_checkpointing()
# Define the model ID and data type
model_id = "Efficient-Large-Model/Sana_600M_1024px_diffusers"
dtype = torch.bfloat16
# Define quantization configuration for FP8
# For simplicity, this example doesn't use os.environ.get as the model loading doesn't require explicit auth in this snippet.
# However, if your model required a Hugging Face token, you would pass token=os.environ.get('HF_TOKEN', '')
quantization_config = NVIDIAModelOptConfig(quant_type="FP8", quant_method="modelopt")
# Load the model with quantization configuration
# In a real scenario, ensure your environment has the necessary NVIDIA drivers and CUDA setup.
try:
print(f"Attempting to load model {model_id} with FP8 quantization...")
model = AutoModel.from_pretrained(
model_id,
subfolder="transformer",
quantization_config=quantization_config,
torch_dtype=dtype,
)
print("Model loaded successfully with quantization enabled.")
# Example of a simple forward pass (replace with actual usage)
# dummy_input = torch.randn(1, 3, 224, 224, dtype=dtype, device='cuda')
# output = model(dummy_input)
# print("Forward pass successful.")
# To save the quantized model (requires a path)
# model.save_pretrained('path/to/sana_fp8', safe_serialization=False)
except Exception as e:
print(f"Error loading or processing model: {e}")
print("Ensure you have `diffusers` installed, a compatible GPU, and potentially `--extra-index-url https://pypi.nvidia.com` during installation if encountering issues.")
Debug
Known issues
gotchaFor full functionality, especially with pre-release versions or specific NVIDIA-optimized components, it is often necessary to install `nvidia-modelopt` using `--extra-index-url https://pypi.nvidia.com`. Without this, certain features or versions might not be available or compatible.fixUse `pip install "nvidia-modelopt[all]" --extra-index-url https://pypi.nvidia.com` for a comprehensive installation.
affects: All versions, especially when using pre-releases (e.g., 0.43.0rcX) or specific NVIDIA integrations.
breakingThe `num_query_groups` parameter in Minitron pruning (specifically for `mcore_minitron`) was deprecated. If you relied on this for pruning, you might need to use an older version of ModelOpt.fixFor applications requiring `num_query_groups` in Minitron pruning, consider using ModelOpt 0.40.0 or earlier, or adapt your pruning strategy to newer APIs if available in the current version.
affects: 0.41.0 and later.
gotchaNVIDIA Model Optimizer has specific Python version requirements (currently Python >=3.10, <3.13). Using incompatible Python versions can lead to installation failures or runtime errors.fixEnsure your Python environment is within the supported range (`python<3.13,>=3.10`). Check `requires_python` on PyPI for the most up-to-date requirements.
affects: All versions.
gotchaThe actual inference performance gains from model optimization (quantization, pruning, distillation) depend heavily on the downstream deployment framework (e.g., TensorRT-LLM, TensorRT) and the specific hardware configuration. `nvidia-modelopt` optimizes the model, but the runtime performance is realized by these specialized inference engines.fixUsers should plan for integration with NVIDIA's TensorRT ecosystem to fully leverage the performance benefits of optimized models. Refer to TensorRT and TensorRT-LLM documentation for deployment best practices.
affects: All versions.
gotchaWhen working with ONNX models, specific opset versions are required for certain quantization types (e.g., INT8 requires opset 13+, FP8 and INT4 require opset 21+). While ModelOpt can automatically upgrade lower opset versions, awareness of these requirements can prevent unexpected behavior or errors.fixVerify the ONNX opset version of your models if encountering issues with quantization. ModelOpt will generally handle upgrades, but manual inspection might be necessary for debugging.
affects: All versions involving ONNX model quantization.
Upgrade
Version history
0.44.0latest on PyPI · released May 13, 2026
Audit
Dependencies
pythonrequiredRequired Python version range.
torchrequiredCore dependency for PyTorch model optimization.
pydanticrequiredUsed for configuration validation.
onnxoptionalOptional dependency for ONNX model optimization, included with '[onnx]' or '[all]' extra.
onnxruntime-gpuoptionalOptional dependency for ONNX runtime, included with '[onnx]' or '[all]' extra (platform/python version dependent).