Install & Compatibility
Where this runs
tested against v2.15.0.20260518 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 1.177s · 18.3MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 3.6s · import 1.104s · 19MB
26MB installed
● package 26MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
xray_recorder
✓ from aws_xray_sdk_stubs.core import xray_recorder
✗ from aws_xray_sdk_stubs.core import xray_recorder
This quickstart demonstrates how to use the underlying `aws-xray-sdk` library, which `types-aws-xray-sdk` provides type hints for. It includes configuration, patching, and a basic traced function using a context manager. To verify the stubs, you would typically run a type checker like MyPy against this code. The commented-out line shows an example of a type error that `types-aws-xray-sdk` would help detect. Remember that for actual tracing, the AWS X-Ray daemon must be running and accessible.
import os
from aws_xray_sdk.core import xray_recorder, patch_all
from aws_xray_sdk.core.segments import Segment
# Install the X-Ray daemon locally or ensure it's available
# Docs: https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html
# Configure X-Ray Recorder (example values)
xray_recorder.configure(
service='MyApplication',
sampling=False, # For simplicity in this example
context_missing='LOG_ERROR',
daemon_address=os.environ.get('AWS_XRAY_DAEMON_ADDRESS', '127.0.0.1:2000')
)
# Apply patches for supported libraries (e.g., boto3, requests)
patch_all()
def my_traced_function(item_id: str) -> str:
# Type checking will ensure 'begin_segment' returns a Segment
with xray_recorder.in_segment('MyFunctionSegment') as segment: # type: Segment
segment.put_annotation('item_id', item_id)
print(f"Processing item {item_id} within segment {segment.id}")
return f"Processed {item_id}"
if __name__ == '__main__':
# Example usage - this code will run and potentially send traces
# For type checking, save this as `app.py` and run `mypy app.py`
result = my_traced_function("12345")
print(result)
# Demonstrate a type error (uncomment and run mypy to see it)
# xray_recorder.configure(service=123) # Expected str, got int
Debug
Known issues
breakingThe AWS X-Ray SDKs and Daemon (the runtime library this package stubs) entered maintenance mode on February 25, 2026. AWS recommends migrating to AWS Distro for OpenTelemetry (ADOT) or OpenTelemetry Instrumentation for new applications to ensure continued feature updates and broader community support.fixFor new development, consider migrating to OpenTelemetry-based instrumentation for AWS X-Ray. For existing applications, continue using `aws-xray-sdk` and `types-aws-xray-sdk` with the understanding that only critical bug fixes and security updates will be provided for the runtime library.
affects: aws-xray-sdk versions from 2.15.0 onwards, and by extension, types-aws-xray-sdk versions for those releases.
gotchaThis package (`types-aws-xray-sdk`) contains only type stubs and provides no runtime code or functionality. It must be installed alongside the actual `aws-xray-sdk` library for any application execution. Installing only the stubs will lead to `ModuleNotFoundError` at runtime if `aws-xray-sdk` is not also present.fixAlways install the runtime library (`pip install aws-xray-sdk`) in your application's environment in addition to the type stubs (`pip install types-aws-xray-sdk`).
affects: All versions
gotchaThe versioning of `types-` packages from Typeshed (e.g., `2.15.0.20260408`) typically indicates compatibility with the corresponding major/minor runtime version (e.g., `aws-xray-sdk==2.15.*`). However, there's no strict guarantee of perfect alignment or that patch versions will always be in sync. A mismatch between the stub version and the runtime library version can lead to incorrect type-checking results or `mypy` errors.fixMonitor your type checker's output. If issues arise, ensure your `aws-xray-sdk` and `types-aws-xray-sdk` versions are as close as possible, ideally with the `types-` package's major.minor.patch matching the runtime library. Pinning stub versions (e.g., `types-aws-xray-sdk==X.Y.Z.*`) can provide stability, but may delay benefits from stub improvements.
affects: All versions
Upgrade
Version history
2.15.0.20260518latest on PyPI · released May 18, 2026
Audit
Dependencies
aws-xray-sdkrequiredProvides runtime functionality that these stubs type-check. Must be installed separately for application execution.
mypyoptionalA common type checker used to leverage these stubs for static analysis.