Install & Compatibility
Where this runs
tested against v0.1.45 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 51.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.7s · import 0.000s · 52MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Experiment
✓ from smexperiments import Experiment
✗ from smexperiments import Experiment
This quickstart demonstrates how to initialize a SageMaker session, create an `Experiment` and `Trial`, and then use a `Tracker` to log parameters and metrics. It includes robust session handling for both SageMaker environments and local execution.
import os
import sagemaker
from sagemaker.experiments import Experiment, Trial
from sagemaker.experiments.tracker import Tracker
# Ensure a SageMaker session is available. In a SageMaker Studio or Job,
# a session is usually automatically configured.
# For local execution, ensure AWS credentials and region are set up (e.g., via environment vars).
try:
sess = sagemaker.Session()
except Exception:
# Fallback for local execution outside a SageMaker context if default fails
import boto3
print("Creating sagemaker.Session with boto3.Session for local execution.")
sess = sagemaker.Session(boto3.Session(region_name=os.environ.get("AWS_REGION", "us-east-1")))
experiment_name = f"my-quickstart-experiment-{os.getpid()}"
trial_name = f"my-quickstart-trial-{os.getpid()}"
# 1. Create an Experiment
# Using .create() ensures a new experiment; .load() would retrieve an existing one.
my_experiment = Experiment.create(
experiment_name=experiment_name,
description="A simple quickstart experiment for sagemaker-experiments",
sagemaker_session=sess
)
print(f"Created Experiment: {my_experiment.experiment_name}")
# 2. Create a Trial within the Experiment
my_trial = Trial.create(
trial_name=trial_name,
experiment_name=experiment_name,
sagemaker_session=sess
)
print(f"Created Trial: {my_trial.trial_name}")
# 3. Use a Tracker to log parameters and metrics (e.g., simulating a training run)
with Tracker.create(display_name="TrainingJobComponent", sagemaker_session=sess) as tracker:
tracker.log_parameters({"learning_rate": 0.01, "epochs": 10, "optimizer": "Adam"})
tracker.log_metrics({"accuracy": 0.85, "loss": 0.15, "f1_score": 0.82})
print(f"Logged data to TrialComponent: {tracker.trial_component.trial_component_name}")
# Associate the tracker's automatically created trial component with our trial
my_trial.add_trial_component(tracker.trial_component)
print("Experiment, Trial, and TrialComponent created and data logged.")
print("You can view these in SageMaker Studio under the Experiments tab.")
# Optional: Clean up created resources (uncomment to enable)
# print("Cleaning up resources...")
# my_trial.delete_all_trial_components()
# my_trial.delete()
# my_experiment.delete()
# print("Cleanup complete.")
Debug
Known issues
breakingThe `sklearn` dependency was renamed to `scikit-learn` in `v0.1.42`. Projects directly depending on `sklearn` might experience `ModuleNotFoundError` if `scikit-learn` is not installed.fixEnsure `scikit-learn` is installed in your environment: `pip install scikit-learn`. Update any direct `import sklearn` statements to `import scikit-learn` if applicable (though typically you import submodules like `from sklearn.ensemble import RandomForestClassifier`).
affects: v0.1.42 and later
breakingSupport for Python 3.6 was officially dropped in `v0.1.42`. Users running `sagemaker-experiments` on Python 3.6 will encounter compatibility issues.fixUpgrade your Python environment to 3.7 or newer. Recommended versions are Python 3.9, 3.10, or 3.11 for broader compatibility and active support.
affects: v0.1.42 and later
gotchaWhen `Tracker.create()` is used outside of a SageMaker Training Job, it automatically creates a new `TrialComponent`. To associate this component with a specific `Trial` created manually (e.g., using `Trial.create()`), you must explicitly add it.fixAfter creating your `Trial` and using `Tracker.create()`, explicitly associate the `TrialComponent`: `my_trial.add_trial_component(tracker.trial_component)`.
affects: All versions
gotchaA bug prior to `v0.1.44` caused issues loading trial components for jobs with mixed-case names. This could lead to difficulties in retrieving or visualizing experiment data.fixUpgrade to `sagemaker-experiments v0.1.44` or newer. If upgrading is not immediately possible, ensure that all SageMaker job names and trial component names use consistent casing, preferably lowercase, to avoid this specific issue.
affects: Prior to v0.1.44
Upgrade
Version history
0.1.45latest on PyPI · released May 17, 2023
Audit
Dependencies
sagemakerrequiredCore SageMaker SDK for interacting with AWS SageMaker services.
boto3requiredAWS SDK for Python, underlying client for SageMaker API calls.
scikit-learnoptionalOptional dependency, required if logging scikit-learn specific artifacts/metrics (note: replaced 'sklearn' in v0.1.42).