• Task
  • Version · 6.0
  • Deliver

Recreate your Python virtual environment for Python 3.12

Last updated: October 19, 2026

Uses

As of Liquibase Secure 6.0, the embedded Python runtime is Python 3.12 (GraalPy 25.0.2). If you run custom policy checks with your own virtual environment using --script-python-executable-path, a virtual environment created with an earlier version of GraalPy targets Python 3.11 and fails with ModuleNotFoundError when a policy check runs. Recreate your virtual environment with a GraalPy release that provides Python 3.12 to continue running custom policy checks.

User group

Action required

Points liquibase.script.python.executablePath at a custom virtual environment

Recreate the virtual environment with a GraalPy release that provides Python 3.12. Follow the steps below.

Uses built-in checks only (no custom virtual environment)

None.

Writes custom checks using the embedded VFS

None. The VFS is rebuilt automatically.

Procedure

1

Save your installed modules

Save your existing virtual environment's module list to a file so you can reinstall it later.

Be sure to:

  • Replace your_venv_path with the path to your existing virtual environment. For example, /opt/liquibase/venv

your_venv_path/bin/pip freeze > requirements.txt

loading
2

Install GraalPy

Download and extract a GraalPy release that provides Python 3.12 (GraalPy 25.0, 25.1, or 25.2), and add its bin directory to your PATH. Use GraalPy rather than a standard Python installation, so that packages with compiled code install in a form the embedded runtime can load.

3

Rename your existing virtual environment

Rename the old virtual environment so the new one can be created at the same path. You can delete the .bak copy after you verify the new environment works.

Be sure to:

  • Replace your_venv_path with the path to your existing virtual environment. For example, /opt/liquibase/venv

mv your_venv_path your_venv_path.bak

4

Create the new virtual environment

Create the virtual environment with GraalPy at the same path as before. Because the path does not change, your --script-python-executable-path configuration does not change.

Be sure to:

  • Replace your_venv_path with the same path your Liquibase configuration points to. For example, /opt/liquibase/venv

graalpy -m venv your_venv_path

5

Reinstall your modules

Reinstall the modules you saved in Step 1 into the new virtual environment.

Be sure to:

  • Replace your_venv_path with the path to your new virtual environment. For example, /opt/liquibase/venv

your_venv_path/bin/pip install -r requirements.txt

loading
6

Verify

Run one of your custom policy checks. If you receive ModuleNotFoundError, see Troubleshoot ModuleNotFoundError for custom policy checks.

PreviousSet up a custom Python virtual environment for Liquibase policy checksNextTroubleshoot ModuleNotFoundError for custom policy checks