ImportError / AttributeError
ImportError: cannot import Guard from guardrails with version <0.4 patterns
Stack trace
Traceback (most recent call last):
File "app.py", line 3, in <module>
from guardrails import Guard
File "/usr/local/lib/python3.10/site-packages/guardrails/__init__.py", line 12, in <module>
raise ImportError(
"guardrails-ai version mismatch: Guard class requires guardrails-ai>=0.5.0. "
"Your version <0.4 uses an incompatible initialization pattern. "
"Use Guard().use() instead of Guard(validators=[...])")
ImportError: guardrails-ai version mismatch: Guard class requires guardrails-ai>=0.5.0. Your version <0.4 uses an incompatible initialization pattern. Use Guard().use() instead of Guard(validators=[...]) Why it happens
Guardrails-ai v0.5+ completely refactored the Guard class initialization API. In v0.4 and earlier, validators were passed directly to Guard(validators=[...]). In v0.5+, Guard is instantiated empty and validators are chained via .use() methods. If your environment has guardrails-ai<0.4 installed, or your code uses old-style Guard initialization, you'll hit an ImportError or AttributeError. This is a deliberate breaking change to support composable, chainable validator workflows.
Detection
Check your guardrails-ai version: `pip show guardrails-ai | grep Version`. If it shows <0.4, upgrade immediately. Search your codebase for Guard(validators=[...]) patterns: any old-style initialization needs rewriting. Add a version assertion at module load time: `import guardrails; assert guardrails.__version__ >= '0.5.0'`.
Causes & fixes
guardrails-ai version installed is <0.4 (or locked in requirements.txt to old version)
Upgrade immediately: `pip install --upgrade guardrails-ai>=0.5.0`. Update requirements.txt or setup.py to `guardrails-ai>=0.5.0`. Run `pip show guardrails-ai` to verify the new version is active.
Code uses old Guard(validators=[...]) pattern from guardrails-ai <0.4
Rewrite Guard initialization using the new .use() chainable API. Replace `Guard(validators=[ToxicLanguage()])` with `Guard().use(ToxicLanguage())`.
Multiple guardrails-ai versions installed in virtualenv or system Python
Delete the virtualenv and recreate it: `rm -rf venv && python -m venv venv && source venv/bin/activate && pip install guardrails-ai>=0.5.0`. This ensures only one version exists.
Using cached imports from guardrails-ai <0.4 in site-packages
Clear pip cache and reinstall: `pip cache purge && pip install --no-cache-dir --upgrade guardrails-ai>=0.5.0`. Then restart your Python interpreter or Jupyter kernel.
Code: broken vs fixed
#!/usr/bin/env python
# guardrails-ai <0.4 BROKEN pattern
import os
from guardrails import Guard
from guardrails.validators import ToxicLanguage, ValidJson
# This will FAIL with ImportError or AttributeError in guardrails-ai >=0.5.0
guard = Guard(
validators=[
ToxicLanguage(on_fail='exception'),
ValidJson(on_fail='filter')
]
)
response = guard.validate("Hello, world!")
print(f"Validated: {response}")#!/usr/bin/env python
# guardrails-ai >=0.5.0 FIXED pattern
import os
from guardrails import Guard
from guardrails.hub import ToxicLanguage, ValidJson
# FIXED: Use Guard().use() chainable API (guardrails-ai v0.5+)
guard = Guard().use(
ToxicLanguage, on_fail='exception'
).use(
ValidJson, on_fail='filter'
)
response = guard.validate("Hello, world!")
print(f"Validated: {response}")Workaround
If you cannot upgrade guardrails-ai immediately due to dependencies, pin to guardrails-ai==0.4.x in requirements.txt and keep the old Guard(validators=[...]) pattern. However, this is temporary: v0.4 is no longer maintained and you must upgrade within 2-4 weeks. To migrate progressively, create a wrapper function that detects the installed version and dispatches to the correct Guard pattern: `def create_guard(validators): if is_v05_plus(): return Guard().use(*validators) else: return Guard(validators=validators)`.
Prevention
Always specify guardrails-ai version constraint in requirements.txt: `guardrails-ai>=0.5.0,<0.6.0` (pin the major.minor). Add a runtime version check at application startup: `import guardrails; assert tuple(map(int, guardrails.__version__.split('.')[:2])) >= (0, 5), 'guardrails-ai 0.5+ required'`. Keep the guardrails hub validators imported from guardrails.hub, not old guardrails.validators. Use CI/CD to catch version mismatches before deployment: run `pip check` in your test pipeline.