How to migrate SOAR playbooks from Python 3.9 to Python 3.13 after upgrading to version 7.x.x

Applicability

Description

After upgrading Splunk SOAR to version 7.x.x or later, the platform automatically attempts to migrate all playbooks from Python 3.9 to Python 3.13. However, not all Python code can be migrated automatically. A playbook can fail the automatic migration if it meets one or more of the following criteria:

• It uses a core Python module that does not exist in Python 3.13.

• It uses a library that does not explicitly list Python 3.13 as a supported version in the python_classifiers field in the library package metadata.

• It contains linting errors that cannot be safely ignored, such as a Python syntax error.

As a result, these playbooks appear under the "Python update required" tab on the Playbooks section of Splunk SOAR user interface post upgrade, specifically after the first automatic migration finishes.

Investigation

After upgrading SOAR to 7.x.x or later, verify whether your playbooks have been automatically migrated to Python 3.13 and use the available logs to troubleshoot any migration failures.

1. Navigate to SOAR > Playbooks and open a playbook. Check the Python version in the playbook editor toolbar. If it shows 3.9, the playbook has not been migrated.
2. Click the Python update required tab on the Playbooks listing page to view all non-migrated playbooks.
3. Review playbook migration errors by inspecting the following log: 

$PHANTOM_HOME/opt/var/log/phantom/automation_migration.log

Resolution

Method 1: Converting individual playbooks to Python 3.13

1. Navigate to SOAR > Playbooks and locate the playbook with Python version 3.9.

2. Open the playbook in the Visual Playbook Editor (VPE).

3. Go to Settings > Update Python Version and select 3.13. Click Save.

4. A pylint validation runs automatically.

5. If validation passes, the playbook is now converted to Python 3.13 and can be verified in the playbooks section.

Method 2: Bulk migrating the playbooks to Python 3.13 (SOAR 7.1.0+)

1. Navigate to SOAR > Playbooks.

2. Click the Python update required tab to display all playbooks still on Python 3.9.

3. Use the checkboxes to select multiple playbooks.

4. Click Convert to Python 3.13 to trigger bulk migration.

5. The process will display a success or failure message along with the pylint errors incase of failure.

Note:

• Failed playbooks display error descriptions directly in the UI, including pylint errors and incompatibility warnings.

• If a playbook fails the Python 3.13 validation, it is not forcibly converted. The playbook remains on Python 3.9 and will be flagged for manual remediation.

• To manually remediate, review the reported errors, update the playbook code to resolve incompatibilities and retry the conversion.

Related Links

https://help.splunk.com/en/splunk-soar/soar-on-premises/release-notes/7.0.0/splunk-soar-on-premises-release-notes/welcome-to-splunk-soar-on-premises-7.0.0

https://help.splunk.com/en/splunk-soar/soar-on-premises/administer-soar-on-premises/7.0.0/introduction-to-splunk-soar-on-premises/how-soar-on-premises-uses-python