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 withatx --version.
- AWS credentials set locally, with the
AWSTransformCustomFullAccessIAM 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.14runtime is available in your Region on the Lambda runtimes page before you deploy.
- SAM CLI recent enough to build
python3.14(sam --version; upgrade withbrew 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
.mdor.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-2aws sts get-caller-identityStep 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.gitcd sam-python-crud-sampleuv venv --python 3.8source .venv/bin/activateuv pip install -r requirements.txtuv pip install -r requirements_dev.txtuv pip install "moto[dynamodb]<3"python -m pytest tests/ -v -o "addopts=" | tee baseline-3.8.txtgit add -A && git commit -m "Baseline: Python 3.8, tests passing"git tag py38-baselineThe tag gives you a fixed point to diff against and roll back to.
Step 2: Start the transformation
atx -tAt 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.13intemplate.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 statusgit branchgit 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/activateuv pip install -r requirements.txt -r requirements_dev.txtpython -m pytest tests/ -v -o "addopts=" | tee result-3.13.txtgit tag py313-completeNon-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 -tOr 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 thematx --versionuv python install 3.14uv run --python 3.14 python --version # expect Python 3.14.xsam --version # must support python3.14 for the build gategit checkout main && git checkout -b upgrade/py314 py313-completeRecord a 3.14 "before" baseline. Failures here are the list of things phase 2 has to fix:
uv venv .venv314 --python 3.14source .venv314/bin/activateuv pip install -r requirements.txt -r requirements_dev.txt 2>&1 | tee before-3.14-install.txtpython -W error::SyntaxWarning -m pytest tests/ -v -o "addopts=" 2>&1 | tee before-3.14-tests.txtdeactivateStep 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-refscurl -sL https://docs.python.org/3.14/whatsnew/3.14.html -o atx-refs/whats-new-3.14.htmlcurl -sL https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html -o atx-refs/lambda-runtimes.htmlThen 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 useannotationlib.get_annotations().
- asyncio.
asyncio.get_event_loop()raisesRuntimeErrorwhen there's no running or current loop; useasyncio.run()orasyncio.new_event_loop().
- Removed
astnode classes (ast.Num,ast.Str,ast.Bytes,ast.NameConstant,ast.Ellipsis). Useast.Constant.
- Removed
pkgutil.find_loader()andpkgutil.get_loader(). Useimportlib.util.find_spec().
- multiprocessing on Linux (and therefore Lambda) now defaults to the
forkserverstart method. Check any code that relies on fork semantics.
- New
SyntaxWarningforreturn,breakorcontinuethat exits afinallyblock (PEP 765).
- Lambda:
Runtime: python3.14intemplate.yaml, Globals and any LayerCompatibleRuntimes, 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-validatedescription: 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 bashset -euo pipefailuv venv .venv314 --python 3.14 --clear -quv 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 1fiecho "PASS: Python 3.14 validation"chmod +x .aws/atx/skills/py314-validate/scripts/validate.shgit 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" -tStep 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-upgradeRun it on a throwaway branch of the phase 1 result. Test before you publish:
git checkout -b test/py314-draft py313-completeatx 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 ." -tCheck 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-upgradeatx custom def list # confirm it is listedatx 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 allocationStep 12: Run the published transformation
Interactive:
git checkout upgrade/py314atx -t> Run python-313-to-314-upgrade on my projectNon-interactive, with
config-314.yaml :codeRepositoryPath: .transformationName: python-313-to-314-upgradevalidationCommands: | bash .aws/atx/skills/py314-validate/scripts/validate.shadditionalPlanContext: | 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..HEADgit diff py313-complete <atx-result-staging-branch>bash .aws/atx/skills/py314-validate/scripts/validate.shgrep -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-completeatx custom def learnings -n python-313-to-314-upgrade # review what the agent learned; archive any bad lessonsQuick 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 -tTest 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:- 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-bashsample in aws-transform-custom-samples . In each repo, run phase 1 withAWS/python-version-upgradeand phase 2 withpython-313-to-314-upgrade, and only start phase 2 if phase 1's validation passed.
- 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-containerssample 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/nullsam delete --stack-name crud-py314-test # only if you deployed in gate 9cd ..rm -rf ./sam-python-crud-sample# optional: remove the definition if this was only a trialatx custom def delete -n python-313-to-314-upgradeDeleting 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
- AWS Transform custom: Workflows (create, save-draft, publish, exec flags, skills, learnings)
- AWS Transform custom: Getting started (installation, authentication, IAM)
- AWS Transform custom: Common use cases (
AWS/python-version-upgrade)
- What's New in Python 3.14 (the breaking-change checklist)
- Lambda runtimes (python3.14 availability and deprecation dates)
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article