- Concept
- Version ยท 6.0.2
- Deliver
Troubleshoot ModuleNotFoundError for custom policy checks
Last updated: November 17, 2026
You may receive this error if --script-python-executable-path is set to the Python executable in your custom virtual environment but you haven't correctly installed your modules:
Error while executing script 'python_scripts/test_python_check.py': ModuleNotFoundError: No module named 'liquibase_checks_python' line: 2
Your virtual environment was built with a different Python version
Before any custom policy check runs, Liquibase checks the Python version of the virtual environment that --script-python-executable-path names. If that environment was built with a Python version other than 3.12, which is the version Liquibase embeds, Liquibase stops with this error and runs no checks:
ERROR [LB-CHK-0024] The Python virtual environment at '<path>' was built with Python 3.11, but this version of Liquibase embeds Python 3.12
This happens with an environment you created for an earlier version of Liquibase Secure, and with one built with GraalPy 25.3 or later. Liquibase cannot use the modules in it, because compiled modules and their bytecode differ between Python versions. The version line in the environment's pyvenv.cfg file shows which Python version built it.
Liquibase skips this check when the environment has no pyvenv.cfg file or the file states no version, and when you set --validate-custom-check-environment=false, which the error message offers. Skipping the check does not make the environment usable, so a mismatched environment then fails with the ModuleNotFoundError shown at the top of this page.
Liquibase Secure 6.0.0 does not run this check, so in 6.0.0 a mismatched environment always fails with ModuleNotFoundError.
Fix: Recreate the environment with Python 3.12.
Your modules aren't installed correctly
Fix: Activate your virtual environment. Then use that environment's pip, not the system pip, to install the liquibase-checks-python package and any other Python modules you want to use: pip install liquibase-checks-python simplejson sqlglot sqlparse
Restart your IDE to see any changes.
Your check script imports a module that is not on the Python import path
Check scripts can only import modules from Liquibase's embedded modules and from the folders on the Python import path, so a helper module isn't importable just because it exists on disk. The error names the missing module and the line that imported it.
Liquibase looks for a module in these places, in this order, and imports the first match:
Liquibase's own embedded modules
The folders you name with
--checks-scripts-python-path, in the order you list themThe folder that holds the check script, when the script is a file on disk
Fix: If the check script is a file on disk, put the helper module in the same folder as the script. Liquibase adds that folder to the import path automatically. If the module lives somewhere else, or the script is packaged rather than a file on disk, for example inside a JAR or ZIP file on the search path, name the module's folder with --checks-scripts-python-path. This parameter is available in Liquibase Secure 5.2.0 and later.
To name more than one folder on Linux or macOS, separate them with a colon:
liquibase checks run --checks-scripts-python-path=/opt/shared/utils:/opt/shared/db
On Windows, separate them with a semicolon and put the value in quotes:
liquibase checks run --checks-scripts-python-path="C:\shared\utils;C:\shared\db"
If your module has the same name as a module found earlier in that order, Liquibase imports the other module and never yours, with no warning. Rename your module so its name is unique.
Your check script imports a module that Liquibase no longer includes
In Liquibase Secure 6.0.2 and later, the built-in Python environment no longer includes urllib3 or some standard library modules. The removed standard library modules are: cgitb, cProfile, ftplib, idlelib, imaplib, nntplib, poplib, profile, pstats, pydoc, pydoc_data, smtplib, telnetlib, test, turtle, turtledemo and xmlrpc. A check script that imports one of them fails with a ModuleNotFoundError that names the module, for example No module named 'ftplib'.
Features of other standard library modules that rely on them also stop working when your script reaches them. For example, an FTP URL in urllib.request fails with the same error, and logging.handlers.SMTPHandler logs the error instead of sending the email.
Fix: Rewrite the check so that it doesn't use the missing module, directly or through another standard library feature.
Your IDE isn't configured to recognize your virtual environment
Your IDE may not display correct syntax highlighting for your Liquibase module imports if you haven't configured your virtual environment correctly, or haven't configured your IDE to recognize your virtual environment.
Fix: configure your IDE to recognize Python-language files and to use the Python executable in your custom virtual environment, then activate your virtual environment.