Troubleshooting Python 3.12 Upgrade

Effective Date: January 21, 2026

Overview

Effective January 21, 2026, Amazon Braket upgrades the Python runtime from 3.10 to 3.12 for all Notebook Instances and managed container images (Base, CUDA-Q, TensorFlow, and PyTorch). This guide provides solutions for common compatibility issues.

Common Error Messages

SDK Python Version Mismatch Error

Error:

RuntimeError: Python version must match between local environment and container. Client is running Python 3.10 locally, but container uses Python 3.12.

Cause: The Braket SDK detected your notebook is running Python 3.10 but the Hybrid Job container is running Python 3.12.

Solution: Either upgrade your notebook to Python 3.12 or pin to Python 3.10 containers.

Cloudpickle Serialization Error

Error:

TypeError: code() argument 13 must be str, not int

Cause: If SDK validation is bypassed, cloudpickle fails to serialize code between Python 3.10 and 3.12 due to a CodeType constructor change in Python 3.12.

Solution: Ensure your notebook and container use the same Python version.

Braket Managed Notebooks

If you're running a Braket Notebook Instance on Python 3.10 and submitting Hybrid Jobs, you will encounter version mismatch errors because the job containers now use Python 3.12 by default.

You have two options:

Hybrid Job Decorator

To use the @hybrid_job decorator, your environment's Python version must match the container's Python version.

Option 1: Use Python 3.12 Containers (Recommended)

If you've upgraded your environment to Python 3.12, it uses the latest tag (default behavior).

Option 2: Use Python 3.10 Containers

If you must stay on Python 3.10, explicitly specify the image_uri parameter in @hybrid_job decorator.

Python 3.10 Container Tags:

The following example is for the us-west-2 Region.

Full Image URIs:

Base:       292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-base-jobs:1.0-cpu-py310-ubuntu22.04
CUDA-Q:     292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-cudaq-jobs:0.12.0-cpu-py310-0.12.0
PyTorch:    292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-pytorch-jobs:2.2.0-gpu-py310-cu121-ubuntu20.04
TensorFlow: 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-tensorflow-jobs:2.14.1-gpu-py310-cu118-ubuntu20.04

Example:

from braket.jobs.hybrid_job import hybrid_job
from braket.devices import Devices

device_arn = Devices.Amazon.SV1

@hybrid_job(
    device=device_arn,
    image_uri="292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-base-jobs:1.0-cpu-py310-ubuntu22.04"
)
def my_job():
    pass

Bring-Your-Own-Container (BYOC)

If your Dockerfile uses a Braket managed image with the latest tag, rebuilding after January 21, 2026 will pull Python 3.12 supported images.

To stay on Python 3.10 supported Braket managed images, update your Dockerfile:

Before (gets Python 3.12 after upgrade):

FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-base-jobs:latest
FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-cudaq-jobs:latest
FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-tensorflow-jobs:latest
FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-pytorch-jobs:latest

After (stays on Python 3.10):

FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-base-jobs:1.0-cpu-py310-ubuntu22.04
FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-cudaq-jobs:0.12.0-cpu-py310-0.12.0
FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-pytorch-jobs:2.2.0-gpu-py310-cu121-ubuntu20.04
FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-tensorflow-jobs:2.14.1-gpu-py310-cu118-ubuntu20.04

Braket Notebook Instance Upgrade

Follow these steps to upgrade to Python 3.12: