AWS Builder Center

Automate AWS Lambda Runtime Upgrades from Python 3.8 to 3.14 with AWS Transform custom

A two-phase, fully tested path from Python 3.8 to 3.14 for Lambda: the AWS-managed transformation to 3.13, then a reusable custom definition for 3.14.

This post upgrades a Python 3.8 Lambda application to Python 3.14 in two phases: the AWS-managed  AWS/python-version-upgrade  transformation takes it to 3.13, then a custom transformation definition takes it to 3.14. It covers every prerequisite, command and test gate, from a fresh clone to a deployed Python 3.14 function, plus how to repeat it across many repos.

Managing Lambda runtime lifecycles

Python 3.8 is a deprecated Lambda runtime, so functions on it no longer get security patches. Jumping straight to 3.14 crosses six minor versions of removals in one go. Splitting it into two phases keeps each change small and testable.
Phase
From → To
Transformation
Support status
1
3.8 → 3.13
 AWS/python-version-upgrade  (AWS-managed)
Tested path for this transformation. AWS's example targets 3.13.
2
3.13 → 3.14
 python-313-to-314-upgrade  (custom definition you create)
Not a tested target, so this guide builds and tests its own definition.
Why a custom definition for phase 2, and not just  additionalPlanContext  on the managed transformation? A definition you own can be tested, versioned, given reference material and reused across every repo. A one-off prompt can't. You can't modify AWS-managed transformations, only steer them with context ( AWS docs ). A quick one-off alternative is shown at the end of phase 2.

Sample application

The walkthrough uses the  SAM Python CRUD sample . It has five Lambda functions that create, read, update, delete and list activity records in DynamoDB, defined in a SAM  template.yaml , with pytest unit tests that mock DynamoDB using  moto .
To run this on your own code, swap the clone in Step 1 for your repository. For example, use  cd "/path/to/your-project"  and keep every other command as is.

Prerequisites

For both phases:
  • AWS Transform CLI ( atx ) installed. Check with  atx --version .
  • AWS credentials set locally, with the  AWSTransformCustomFullAccess  IAM policy. Phase 2 needs this full-access policy, because it creates and publishes a transformation definition. The execute-only policy isn't enough.
  • Git installed, and the target folder committed as a git repo.
  • The  uv  package manager.
  • Node.js 22 or later, which the CLI requires.
Additional for phase 2 (3.13 → 3.14):
  • Python 3.14 interpreter installed through uv, so validation runs on the real target:  uv python install 3.14 .
  • Lambda runtime check: confirm the  python3.14  runtime is available in your Region on the  Lambda runtimes page  before you deploy.
  • SAM CLI recent enough to build  python3.14  ( sam --version ; upgrade with  brew upgrade aws-sam-cli ). It's only needed for the build and deploy test gates.
  • Dependency readiness: every pinned package must ship 3.14-compatible wheels. Check with  uv pip install --python 3.14 -r requirements.txt --dry-run .
  • Reference material for the definition, as text files: the Python "What's New in 3.14" page saved as  .md  or  .html , plus your own before/after examples. The CLI accepts text files only, up to 10 MB in total.
  • Optional: the free-threaded build, if you want to test the no-GIL interpreter later:  uv python install 3.14t .
macOS on Apple Silicon: run everything from a native ( arm64 ) terminal.  uname -m  must print  arm64 . Under Rosetta, Homebrew and the Command Line Tools fail.

Phase 1 hands-on: Python 3.8 → 3.13 (AWS-managed transformation)

Phase 1 runs the AWS-managed transformation as it is. Its result, a 3.13 codebase with all tests passing, is the starting point for phase 2.

Step 0: Set up credentials and the Region

export AWS_PROFILE=<your-profile>
export AWS_REGION=ap-southeast-2
aws sts get-caller-identity

Step 1: Prepare the sample project

Clone the repo, create a Python 3.8 environment and record a passing baseline:
git clone https://github.com/aws-samples/sam-python-crud-sample.git
cd sam-python-crud-sample
uv venv --python 3.8
source .venv/bin/activate
uv pip install -r requirements.txt
uv pip install -r requirements_dev.txt
uv pip install "moto[dynamodb]<3"
python -m pytest tests/ -v -o "addopts=" | tee baseline-3.8.txt
git add -A && git commit -m "Baseline: Python 3.8, tests passing"
git tag py38-baseline
The tag gives you a fixed point to diff against and roll back to.

Step 2: Start the transformation

atx -t
At the prompt:
> list all the transformations available
> Run AWS/python-version-upgrade on my project. The target Python version is Python 3.13.
 -t  trusts all tools, so the agent runs shell commands without asking. Leave it off the first time if you want to approve each command.

Step 3: Transformation planning

The agent proposes a plan covering:
  • the runtime update ( Runtime: python3.13  in  template.yaml )
  • dependency checks
  • deprecated code patterns
  • Lambda configuration
  • infrastructure-as-code changes
Review it, add feedback (for example "keep moto on a version that supports 3.13"), then type  proceed .

Step 4: Transformation execution and validation

The agent applies the changes and commits each step to a local  atx-result-staging-*  branch. It fixes build and test errors itself, then runs a final validation of the result against the plan, including the unit tests.

Step 5: Verify the changes

Exit with  /quit , then check the result:
git status
git branch
git diff py38-baseline <atx-result-staging-branch>
Merge the result and tag it as the phase 2 starting point:
git checkout main && git merge <atx-result-staging-branch>
uv venv --python 3.13 --clear && source .venv/bin/activate
uv pip install -r requirements.txt -r requirements_dev.txt
python -m pytest tests/ -v -o "addopts=" | tee result-3.13.txt
git tag py313-complete

Non-interactive mode

Use this for CI/CD or bulk runs:
atx custom def exec -p . -n AWS/python-version-upgrade \
--configuration "validationCommands=pytest,additionalPlanContext=The target Python version to upgrade to is Python 3.13" -x -t
Or pass the same settings in a  config.json :
{
"codeRepositoryPath": ".",
"transformationName": "AWS/python-version-upgrade",
"validationCommands": "pytest",
"additionalPlanContext": "The target Python version to upgrade to is Python 3.13"
}
atx custom def exec --configuration 'file://config.json'

Phase 2 hands-on: Python 3.13 → 3.14 (custom transformation definition)

There's no tested managed transformation for 3.14, so in this phase you write your own:  python-313-to-314-upgrade . You give it reference material and a validation skill, test it as a draft, then publish it so every repo uses the same tested version.

Step 6: Extra prerequisites for phase 2

atx update # client-side skills (Step 8) need CLI 2.0 or later; 1.0.x won't load them
atx --version
uv python install 3.14
uv run --python 3.14 python --version # expect Python 3.14.x
sam --version # must support python3.14 for the build gate
git checkout main && git checkout -b upgrade/py314 py313-complete
Record a 3.14 "before" baseline. Failures here are the list of things phase 2 has to fix:
uv venv .venv314 --python 3.14
source .venv314/bin/activate
uv pip install -r requirements.txt -r requirements_dev.txt 2>&1 | tee before-3.14-install.txt
python -W error::SyntaxWarning -m pytest tests/ -v -o "addopts=" 2>&1 | tee before-3.14-tests.txt
deactivate

Step 7: Gather reference material

The agent only knows what you give it. Put text-only references in one folder (10 MB limit; no PDFs or images):
mkdir -p atx-refs
curl -sL https://docs.python.org/3.14/whatsnew/3.14.html -o atx-refs/whats-new-3.14.html
curl -sL https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html -o atx-refs/lambda-runtimes.html
Then add  atx-refs/py314-checklist.md , your own short list of 3.13 → 3.14 changes to look for. Check each item against the What's New page before you rely on it:
  • Deferred annotations (PEP 649/749). Code that reads  __annotations__  directly should use  annotationlib.get_annotations() .
  • asyncio.  asyncio.get_event_loop()  raises  RuntimeError  when there's no running or current loop; use  asyncio.run()  or  asyncio.new_event_loop() .
  • Removed  ast  node classes ( ast.Num ,  ast.Str ,  ast.Bytes ,  ast.NameConstant ,  ast.Ellipsis ). Use  ast.Constant .
  • Removed  pkgutil.find_loader()  and  pkgutil.get_loader() . Use  importlib.util.find_spec() .
  • multiprocessing on Linux (and therefore Lambda) now defaults to the  forkserver  start method. Check any code that relies on fork semantics.
  • New  SyntaxWarning  for  return ,  break  or  continue  that exits a  finally  block (PEP 765).
  • Lambda:  Runtime: python3.14  in  template.yaml , Globals and any Layer  CompatibleRuntimes , plus build images and CI matrices.
  • Dependencies: bump any pin without 3.14 wheels to the lowest version that supports 3.14. For moto 5 and later, the decorators change to  @mock_aws .

Step 8: Add a project-level validation skill

This gives the agent a check it must pass, and makes each run measured against the same bar. Create  .aws/atx/skills/py314-validate/SKILL.md :
---
name: py314-validate
description: Validates that the project builds and passes tests on Python 3.14 with no 3.13 runtime references left
---
# Python 3.14 validation

CRITICAL: Run `bash .aws/atx/skills/py314-validate/scripts/validate.sh` after every change set.
The transformation is complete only when it exits 0.
Then create  .aws/atx/skills/py314-validate/scripts/validate.sh :
#!/usr/bin/env bash
set -euo pipefail
uv venv .venv314 --python 3.14 --clear -q
uv pip install -q --python .venv314/bin/python -r requirements.txt -r requirements_dev.txt
.venv314/bin/python -W error::SyntaxWarning -m compileall -q src/ tests/ 2>/dev/null || .venv314/bin/python -W error::SyntaxWarning -m compileall -q .
.venv314/bin/python -W error::SyntaxWarning -m pytest tests/ -q -o "addopts="
if grep -rn "python3\.1[0-3]\|python3\.[89]" --include=*.yaml --include=*.yml --include=*.toml --include=*.json . | grep -v ".venv"; then
echo "FAIL: old runtime references remain"; exit 1
fi
echo "PASS: Python 3.14 validation"
chmod +x .aws/atx/skills/py314-validate/scripts/validate.sh
git add .aws atx-refs && git commit -m "Add py314 references and validation skill"

Step 9: Create the transformation definition

Option A is interactive, which is recommended for the first build:
atx
> I want to create a new transformation definition named python-313-to-314-upgrade.
> Objective: upgrade Python 3.13 projects, including AWS Lambda functions defined with AWS SAM, to Python 3.14.
> Source state: Python 3.13, Runtime python3.13. Target state: Python 3.14, Runtime python3.14.
> Required changes: update runtime declarations (template.yaml, Globals, Layers, pyproject, CI), upgrade
> dependencies to the lowest 3.14-compatible versions, replace removed or deprecated APIs, fix new SyntaxWarnings.
> CRITICAL: do not change business logic. CRITICAL: validation passes only when
> "bash .aws/atx/skills/py314-validate/scripts/validate.sh" exits 0.
> Take a look at the docs we have here: ./atx-refs/
Review the draft definition the agent writes (a  SKILL.md  plus  references/ ). Then save it locally when asked, and note the folder path it reports.
Option B is headless:
atx -x "create a transformation definition to upgrade Python 3.13 AWS Lambda and SAM projects to Python 3.14 named python-313-to-314-upgrade with references docs ./atx-refs" -t

Step 10: Save as a draft and test it

atx custom def save-draft -n python-313-to-314-upgrade \
--description "Upgrade Python 3.13 Lambda/SAM projects to Python 3.14" \
--sd ./python-313-to-314-upgrade
Run it on a throwaway branch of the phase 1 result. Test before you publish:
git checkout -b test/py314-draft py313-complete
atx custom def exec -n python-313-to-314-upgrade -p . \
-c "bash .aws/atx/skills/py314-validate/scripts/validate.sh"
If the draft won't run by name, apply it from the saved folder instead:
atx -x "apply transformation definition ./python-313-to-314-upgrade to ." -t
Check the diff, then improve the definition from what went wrong. Reopen  atx , say you want to modify  python-313-to-314-upgrade , give the agent the failing output or a corrected code example, save the draft again, and rerun on a fresh branch. Repeat until  validate.sh  passes with no manual edits.

Step 11: Publish to the registry

atx custom def publish -n python-313-to-314-upgrade \
--description "Upgrade Python 3.13 Lambda/SAM projects to Python 3.14 (tested on sam-python-crud-sample)" \
--sd ./python-313-to-314-upgrade
atx custom def list # confirm it is listed
atx custom def tag --arn arn:aws:transform-custom:ap-southeast-2:<account-id>:package/python-313-to-314-upgrade \
--tags '{"team":"platform","CostCenter":"<cc>"}' # optional: tags for cost allocation

Step 12: Run the published transformation

Interactive:
git checkout upgrade/py314
atx -t
> Run python-313-to-314-upgrade on my project
Non-interactive, with  config-314.yaml :
codeRepositoryPath: .
transformationName: python-313-to-314-upgrade
validationCommands: |
bash .aws/atx/skills/py314-validate/scripts/validate.sh
additionalPlanContext: |
Target is Python 3.14 and Lambda runtime python3.14.
CRITICAL: preserve business logic; change only what 3.14 compatibility requires.
atx custom def exec --configuration file://config-314.yaml -x -t --limit 60
 --limit 60  caps the run at 60 agent minutes. If it hits the cap, resume with  atx --conversation-id <id> -t --limit <higher> .

Step 13: Verify the changes

git log --oneline py313-complete..HEAD
git diff py313-complete <atx-result-staging-branch>
bash .aws/atx/skills/py314-validate/scripts/validate.sh
grep -rn "python3.13" --include=*.yaml . || echo "no 3.13 runtime references left"
git checkout upgrade/py314 && git merge <atx-result-staging-branch> && git tag py314-complete
atx custom def learnings -n python-313-to-314-upgrade # review what the agent learned; archive any bad lessons

Quick alternative: the managed transformation with context

For a single repo where you don't need a reusable definition, steer the managed transformation instead. It's faster, but outside the tested range, so the test plan below matters more:
atx custom def exec -p . -n AWS/python-version-upgrade \
--configuration "validationCommands=bash .aws/atx/skills/py314-validate/scripts/validate.sh,additionalPlanContext=Upgrade from Python 3.13 to Python 3.14 and set the Lambda runtime to python3.14" -x -t

Test plan

Each gate must pass before the next one starts. A failure goes back into the transformation as feedback; you don't patch it by hand. Gates 1–5 run after both phase 1 and phase 2. Gates 6–9 run on the final 3.14 build.
#
Gate
Command
Pass criteria
1
Baseline parity
 python -m pytest tests/ -v -o "addopts="  on the tagged baseline and on the result
Same test count. Every test that passed on 3.8 still passes. No tests deleted or skipped to get there.
2
Clean install
 uv venv --python 3.1x --clear && uv pip install -r requirements.txt -r requirements_dev.txt 
Installs with no resolver conflicts and no source builds of packages that should have wheels.
3
Compile and warnings
 python -W error::SyntaxWarning -W error::DeprecationWarning -m compileall -q . 
Exit 0. No invalid escape sequences, no  finally  control-flow warnings.
4
Static scan
 uvx ruff check --target-version py314 .  and  uvx vermin --target=3.14- --no-tips . 
No new errors compared with the baseline. No use of removed modules or APIs.
5
Diff review
 git diff <baseline-tag> <result-branch> --stat , then read the full diff
Only runtime, dependency and compatibility changes. No business-logic edits. Every changed file is explained in the agent's summary.
6
Runtime declarations
 grep -rn "python3\." template.yaml  plus CI files
Every function, Globals and Layer entry says  python3.14 . Nothing older remains.
7
SAM build
 sam build --use-container 
Builds on the python3.14 build image with no errors.
8
Local invoke
 sam local invoke <FunctionName> -e events/<event>.json  for each of the 5 functions
Each returns the same status code and response shape as the 3.8 baseline.
9
Deployed smoke test (non-prod)
 sam deploy --guided --stack-name crud-py314-test , then call each API route
Create, read, update, delete and list all succeed against DynamoDB. CloudWatch shows  Runtime Version: python:3.14 . No errors or init-duration regression of more than 20% in the logs.
Rollback: each phase ends on a tag ( py38-baseline ,  py313-complete ,  py314-complete ). To roll back code, run  git checkout <tag> . To roll back a deployed function, redeploy the previous tag's template, or keep the 3.13 version as a Lambda alias until gate 9 passes.
Evidence to keep:  baseline-3.8.txt ,  result-3.13.txt ,  before-3.14-tests.txt , the final  validate.sh  output, the  git diff --stat  for each phase, and the agent-minutes figure from each run (shown at exit, or type  /usage ).

How to scale this to multiple Lambda function upgrades

Once  python-313-to-314-upgrade  is published, the two phases become a pipeline you can run across every repo. Track progress centrally with a campaign in the AWS Transform web application, and choose one of two execution models:
  1. Batch script execution. List your repos in a CSV or JSON file and run both phases per repo, in parallel with retries. Use the  scaled-execution-bash  sample in  aws-transform-custom-samples . In each repo, run phase 1 with  AWS/python-version-upgrade  and phase 2 with  python-313-to-314-upgrade , and only start phase 2 if phase 1's validation passed.
  1. Containerised execution on AWS. Run AWS Batch on Fargate with a REST API, IAM credentials and CloudWatch monitoring, deployed with AWS CDK. Use the  scaled-execution-containers  sample in the same repo.
Commit  .aws/atx/skills/py314-validate/  into each repo, or a shared template, so every run is held to the same validation gate. The lessons the definition learns in early runs are applied to later ones automatically.

Cleanup

deactivate 2>/dev/null
sam delete --stack-name crud-py314-test # only if you deployed in gate 9
cd ..
rm -rf ./sam-python-crud-sample
# optional: remove the definition if this was only a trial
atx custom def delete -n python-313-to-314-upgrade
Deleting the definition is permanent. Keep it if you plan to run phase 2 on other repos.

Conclusion

The AWS-managed transformation handles the hard part of Python 3.8 → 3.13 out of the box. A custom definition, with your references and a validation skill, extends it to 3.14 in a way you can repeat across repos. You get two short, tested phases, each tagged, so you can roll back at either step. You also end up with a reusable  python-313-to-314-upgrade  asset for the next repo. Next steps: run both phases on one real repo, publish the definition, then scale with a campaign.
Note: the 3.13 → 3.14 checklist in Step 7 comes from the Python 3.14 release notes, not from AWS Transform documentation. Check it against the What's New page before relying on it.

References

Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article