SageMaker Python SDK v3: ModelTrainer and ModelBuilder Replace the Estimator and Model Classes
A library for training and deploying machine learning models on Amazon SageMaker
At a glance
- What is it?
- The AWS SageMaker Python SDK moved to a modular 3.x line that drops Estimator, Model and Predictor in favour of ModelTrainer and ModelBuilder. This piece covers what the migration actually breaks, how the new training and inference flows are wired, and who should stay on 2.x.
- Who is it for?
- Adopt 3.x if you are starting a new SageMaker training or inference workflow and can pin the split packages (sagemaker-core, sagemaker-train, sagemaker-serve, sagemaker-mlops) together. Stay on sagemaker==2.* if your codebase imports Estimator, Model, Predictor or any framework-specific estimator or model class, because the README states those interfaces are not supported in V3.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The 3.x Release Deletes the Classes Most SageMaker Code Imports
The README states this plainly: older interfaces such as Estimator, Model, Predictor and all their subclasses will not be supported in V3. That is not a deprecation warning with a removal date. It is the current state of the 3.x line, and the repository ships a separate v3-examples folder rather than updating the 2.x examples in place. The SDK has been publishing 3.x releases steadily through 2026 (v3.19.0, v3.20.0, v3.21.0 in August alone), so the new line is the actively developed one.
The problem this solves is sprawl. In 2.x, a PyTorch job used PyTorchEstimator, a scikit-learn job used SKLearnEstimator, deployment used PyTorchModel or TensorFlowModel or SKLearnModel or XGBoostModel, and each of those carried its own argument surface. V3 collapses training into one ModelTrainer class and inference into one ModelBuilder class. The README describes the result as a structured interface with auto-generated configs aligned with AWS APIs. If you have ever written the same instance_count and instance_type pair five times in one notebook with five different class names, the motivation is obvious.
Who it is for: teams running training and inference on Amazon SageMaker who want the SDK to look like one API instead of a family of framework adapters. Who it is not for: anyone with a working 2.x pipeline and no reason to touch it.
ModelTrainer, InputData and the Shift to Explicit Config Objects
The 2.x example in the README builds an Estimator with image_uri, role, instance_count, instance_type and output_path, then calls fit with a dictionary mapping channel names to S3 paths. The 3.x version splits that into two objects. ModelTrainer takes training_image and role. InputData takes channel_name and data_source. Training is invoked as trainer.train(input_data_config=[train_data]).
The data flow is the same underneath: a container image, an IAM role, an S3 data source, an S3 output location. What changed is where the parameters live. Channel configuration moved out of the fit call and into an InputData list, which makes multi-channel setups explicit rather than a dictionary literal. The README presents this as reduced boilerplate, and for a single-channel job it is arguably more lines, not fewer. The trade is that the config objects can be generated and validated against AWS API shapes, which a loose dict cannot.
On the inference side, ModelBuilder takes model and model_path, and build() returns something you call invoke on. The 2.x path was Model plus Predictor plus deploy, with initial_instance_count and instance_type passed at deploy time. The README's 3.x snippet does not show instance type or count at all, and it does not show the argument list for invoke. That is a gap worth noting: the README gives the shape of the new API but not the full parameter surface. The v3-examples notebooks are where the README points for actual usage patterns, and you will need them.
Installing 3.x and Rolling Back to 2.x
Installation is a single pip command, and the README gives it directly:
pip install --upgrade sagemaker
If you need to return to the previous line, the README gives that too:
pip install sagemaker==2.*
That pin is the most important line in the migration guide. Because 3.x is published to the same sagemaker package name on PyPI, an unpinned dependency in a requirements file will pull the new major version on the next build. The README also notes that 3.x splits functionality across separate packages: sagemaker-core, sagemaker-train, sagemaker-serve and sagemaker-mlops. The README does not state whether installing sagemaker pulls all four as dependencies or whether you install them individually. Verify that before you write a lockfile, because a partial install would show up as an ImportError on sagemaker.train or sagemaker.serve rather than as a version conflict.
The imports in the README's examples are the concrete contract: from sagemaker.train import ModelTrainer, from sagemaker.train.configs import InputData, from sagemaker.serve import ModelBuilder. Those three paths are what your code has to resolve.
The Local and Distributed Training Paths Are Documented Only as Notebooks
The README lists five training examples and several inference examples, all as .ipynb files under v3-examples. The training list includes custom distributed training, distributed local training, hyperparameter training, JumpStart training and local training. The inference list includes a HuggingFace example, an in-process mode example and an inference spec example.
This is a real limitation for anyone evaluating the SDK from the README alone. Prose documentation for the new classes is not in the README; the reference lives at sagemaker.readthedocs.io, and the README does not say whether that site has been rewritten for 3.x or still leads with 2.x material. The presence of a dedicated v3-examples folder alongside the older examples suggests the two coexist rather than one replacing the other.
Local training and in-process mode are the two entries worth flagging. Local execution means the training container runs on your machine rather than on SageMaker infrastructure, which is useful for debugging a container before paying for an instance. In-process mode appears to be an inference option where the model runs in the same process rather than behind a managed endpoint. The README names both but does not describe either. If your workflow depends on either, the notebook is the specification, and you should read it before assuming the 3.x API matches what you did in 2.x.
Where 3.x Is the Wrong Choice
The clearest failure mode is a 2.x codebase with deep imports. The README says Estimator, Model, Predictor and all subclasses are unsupported in V3. That includes the framework-specific estimators and models the SDK has shipped for years. A training script that imports PyTorchEstimator, sets hyperparameters on it, and calls fit will not run against 3.x. There is no compatibility shim described in the README.
The second case is a team with a stable pipeline and no appetite for churn. The SDK is publishing 3.x releases roughly every one to two weeks based on the dates in the release list. That cadence is normal for an actively developed SDK, but it means the 3.x API surface is still settling. If your training and inference code is working on 2.x and nobody is blocked by the class sprawl, the migration buys you architectural tidiness and costs you a rewrite of every entry point plus whatever the notebooks reveal about parameters the README omits.
The third case is anyone who needs the SDK's behaviour pinned by documentation rather than by example. The README shows one training call and one inference call. Distributed training, hyperparameter tuning, JumpStart and local mode are all notebook-only as far as the supplied material goes. If your compliance or review process requires prose documentation for the API you depend on, 3.x is harder to sign off on today than 2.x.
What the Alternative Actually Gives You
The direct alternative is staying on the 2.x line, which the README supports as a first-class option with pip install sagemaker==2.*. The difference is not cosmetic. In 2.x you choose a class per framework: PyTorchEstimator for training, PyTorchModel for deployment, Predictor for invocation. Each class carries framework-aware defaults, so the SDK knows how to wire a PyTorch container without you specifying as much. In 3.x you choose ModelTrainer and ModelBuilder and pass an image and a role, which is more uniform but also less opinionated about the framework inside the container.
That is the real trade. The 2.x design duplicates concepts across frameworks in exchange for framework-specific convenience. The 3.x design removes the duplication and pushes framework detail back into the container image and the config objects you supply. If you train with one framework and never touch the others, 2.x's duplication costs you little and its defaults save you configuration. If you run PyTorch, TensorFlow, MXNet and scikit-learn jobs side by side, 3.x's single surface is worth the extra explicitness.
The other alternative is skipping the SDK's training abstractions and calling the SageMaker APIs directly. The README positions 3.x as an object-oriented layer whose configs are aligned with AWS APIs, which implies the underlying API calls are still there. The SDK's value is the config generation and the container plumbing, not the API itself. If you already have that plumbing, the SDK is optional.
Licence, Maintenance and What to Check Before Upgrading
The project is Apache-2.0. That permits commercial use, modification and redistribution provided the licence and notices are preserved, and it includes a patent grant. Apache-2.0 does not require you to publish your own code. This is a general description of the licence text, not legal advice; if you vendor or modify the SDK, have your own counsel review the notice requirements.
Maintenance cost is dominated by the version pin, not by the licence. The 3.x line is releasing frequently, and each release can move the ModelTrainer and ModelBuilder surfaces while the API settles. Pin an exact version in your lockfile rather than a range, and treat upgrades as deliberate events where you re-run the v3-examples patterns closest to your workload. The rollback path is one command, which keeps the risk bounded.
The split into sagemaker-core, sagemaker-train, sagemaker-serve and sagemaker-mlops is the other maintenance consideration. Four packages means four version constraints to keep consistent. The README lists the packages but does not describe their versioning relationship, so verify whether they are released in lockstep or independently before you pin them separately. If they move independently, a mixed set is a plausible source of breakage that will not show up until runtime.
What to verify first, in order: whether importing sagemaker.train and sagemaker.serve works after a clean pip install --upgrade sagemaker; whether the ModelBuilder constructor in your installed version accepts the arguments the README's snippet implies; and whether the v3-examples notebook for your workload uses parameters the README does not mention.
Editorial conclusion
Adopt 3.x if you are starting a new SageMaker training or inference workflow and can pin the split packages (sagemaker-core, sagemaker-train, sagemaker-serve, sagemaker-mlops) together. Stay on sagemaker==2.* if your codebase imports Estimator, Model, Predictor or any framework-specific estimator or model class, because the README states those interfaces are not supported in V3. Before committing, open the v3-examples notebooks for the training and inference patterns closest to your workload and confirm the exact ModelTrainer and ModelBuilder constructor arguments your code will need.
Community notes