InvalidInstallationError
guardrails.validators.InvalidInstallationError: hub install requires guardrails-ai>=0.5
Stack trace
Traceback (most recent call last):
File "<your_script>.py", line X, in <module>
from guardrails.hub import ToxicLanguage
File "/path/to/site-packages/guardrails/hub/__init__.py", line YZ, in _load_validator
raise InvalidInstallationError(
'Hub validator "ToxicLanguage" requires guardrails-ai>=0.5.0 but found guardrails-ai==0.4.2'
)
guardrails.validators.InvalidInstallationError: hub install requires guardrails-ai>=0.5.0 Why it happens
Guardrails Hub validators (ToxicLanguage, ValidJson, etc.) are versioned independently from the core guardrails-ai package. When you try to import a validator from the hub, it checks the installed guardrails-ai version against its minimum requirement. If your installed guardrails-ai is older than 0.5.0, the validator refuses to load because its code depends on APIs that only exist in guardrails-ai>=0.5.0. This typically happens when you upgrade validators without upgrading the core package, or when different packages in your environment have conflicting dependency pins.
Detection
Check your installed guardrails-ai version before importing hub validators: run `pip show guardrails-ai` and verify the version is >=0.5.0. Add a simple version check at the top of your script to fail fast with a clear message before validator import attempts.
Causes & fixes
Installed guardrails-ai version is older than 0.5.0 (e.g., 0.4.2 or 0.3.x)
Upgrade guardrails-ai to the latest 0.5.x version: run `pip install --upgrade guardrails-ai>=0.5.0` and verify with `pip show guardrails-ai`
guardrails-ai is pinned to an old version in your requirements.txt or poetry.lock file
Remove the pinned version constraint (e.g., change `guardrails-ai==0.4.2` to `guardrails-ai>=0.5.0`) in your requirements file, then run `pip install --upgrade -r requirements.txt`
A dependency of another package (e.g., in setup.py or pyproject.toml) pins guardrails-ai to <0.5.0, overriding your upgrade
Run `pip show guardrails-ai` and check the dependency tree with `pipdeptree | grep guardrails`. Update the parent dependency constraint or use `pip install --upgrade --force-reinstall guardrails-ai>=0.5.0` to override
Poetry or pipenv lock file has stale guardrails-ai version locked in
Run `poetry lock --no-update` then `poetry update guardrails-ai` (or `pipenv lock --clear && pipenv sync`) to refresh the lock with the latest compatible version
Code: broken vs fixed
import os
from guardrails.hub import ToxicLanguage # ERROR: raises InvalidInstallationError if guardrails-ai<0.5
guard = Guard().use(ToxicLanguage, on_fail='exception')
result = guard.validate('This is a test')
print(result)import os
import subprocess
import sys
from packaging import version
# FIX: Check guardrails-ai version before importing hub validators (guardrails-ai>=0.5 required)
try:
import guardrails
installed_version = guardrails.__version__
required_version = '0.5.0'
if version.parse(installed_version) < version.parse(required_version):
print(f'ERROR: guardrails-ai {installed_version} is too old. Upgrading to >=0.5.0...')
subprocess.check_call([sys.executable, '-m', 'pip', 'install', '--upgrade', 'guardrails-ai>=0.5.0'])
print('Upgrade complete. Please re-run your script.')
sys.exit(0)
except ImportError:
subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'guardrails-ai>=0.5.0'])
print('Installation complete. Please re-run your script.')
sys.exit(0)
from guardrails import Guard # NOW safe to import
from guardrails.hub import ToxicLanguage
guard = Guard().use(ToxicLanguage, on_fail='exception')
result = guard.validate('This is a test')
print(f'Validation result: {result}')Workaround
If you cannot upgrade guardrails-ai immediately, avoid importing validators from the hub and write custom validators inline instead. Define a Pydantic model and use Guard.from_pydantic(your_model) instead of relying on hub validators. This keeps you on the old guardrails-ai version temporarily, but you lose validator updates and community validators. This is NOT recommended for production: upgrade guardrails-ai as soon as possible.
Prevention
Pin guardrails-ai to a known-good version in your requirements.txt or pyproject.toml (e.g., `guardrails-ai>=0.5.0,<1.0.0`), run `pip install --upgrade guardrails-ai` during your CI/CD setup step, and add a startup assertion in your application that checks the version and fails fast if it's too old. Use `pip-audit` or `safety check` in your CI to catch dependency drift before production.