Troubleshoot ModuleNotFoundError for custom policy checks

Your virtual environment was built with a different Python version

Liquibase Secure 6.0 embeds Python 3.12, and it looks for your installed modules only where a Python 3.12 virtual environment keeps them. An environment built with another Python version keeps its modules somewhere else. That includes an environment you created for an earlier version of Liquibase Secure, and one built with GraalPy 25.3 or later. Liquibase finds none of its modules, so each one you import fails with this error even though pip list shows it installed.

The version line in the environment's pyvenv.cfg file shows which Python version built it.

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 sqlparse urllib3

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:

1. Liquibase's own embedded modules

2. The folders you name with --checks-scripts-python-path, in the order you list them

3. The 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 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.