segmentation_models_pytorch: a PyTorch encoder-decoder library for semantic segmentation
Semantic segmentation models with 500+ pretrained convolutional and transformer-based backbones.
At a glance
- What is it?
- SMP wraps 12 segmentation architectures around 800+ pretrained encoders behind a two-line API. It is a strong fit when you already have a PyTorch training loop and need a decoder head; it is not a training framework and does not cover 3D volumes.
- Who is it for?
- Adopt segmentation_models_pytorch if you already have a PyTorch training loop and want a decoder head attached to a pretrained encoder, and if your data is 2D. Do not adopt it expecting a training framework, a 3D pipeline, or a web service; the library builds torch.nn.Module objects and stops there.
- Can I use it commercially?
- Yes. MIT 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 last received commits 2 days ago.
- 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
What segmentation_models_pytorch solves, and who is on the other end of it
Writing a segmentation network from scratch means two separate jobs. The first is the encoder: a convolutional or transformer backbone that turns an image into feature maps and needs pretrained weights to converge in reasonable time. The second is the decoder: the part that upsamples those features back to pixel resolution. Most projects get stuck on the second job, and on wiring the two together correctly.
segmentation_models_pytorch (SMP) packages both halves. The README describes the main features as a "Super simple high-level API (just two lines to create a neural network)", 12 encoder-decoder architectures including Unet, Unet++, Segformer and DPT, and 800+ pretrained encoders with timm support. The intended user is an engineer who already trains models in PyTorch and wants a decoder head rather than a full pipeline. SMP is a library of torch.nn.Module objects. It does not ship a Trainer, a data loader, or a serving layer, so if you need those, you are writing them or importing them from elsewhere.
The encoder-decoder split and the preprocessing function that comes with it
Every architecture in SMP follows the same shape: an encoder produces a list of feature maps at different strides, and a decoder consumes that list and produces logits at the input resolution. The encoder is selected by name, and the name is what determines the weights. In the README example, encoder_name="resnet34" with encoder_weights="imagenet" builds a ResNet-34 backbone initialized from ImageNet weights.
The less obvious half of the mechanism is preprocessing. Encoders were trained with specific normalization statistics, and the README is explicit that matching them "may give you better results (higher metric score and faster convergence)", while also noting it is "not necessary" if you train the whole model rather than only the decoder. The library exposes this through get_preprocessing_fn, which returns a callable for a given encoder and pretrained weight set. Because timm is a dependency, the encoder namespace is much larger than the dozen architectures suggests. The README says 800+ pretrained encoders, while the repository description says 500+; treat the exact number as a moving target and check the encoder table in the docs for the name you intend to use.
Installing segmentation_models_pytorch and running a first Unet
The package is published on PyPI as segmentation-models-pytorch, and the README links to that page from its badge. The repository's pyproject.toml requires Python >=3.10 and lists torch>=1.11, torchvision>=0.12, timm>=0.9, numpy, pillow, safetensors, huggingface-hub and tqdm as dependencies, so pip will pull a large dependency set along with it.
pip install segmentation-models-pytorchAfter that, building a model is the two-line construction the README advertises. This block is copied from the README's quick start, with in_channels=1 for grayscale input and classes=3 for a three-class output.
import segmentation_models_pytorch as smp
model = smp.Unet(
encoder_name="resnet34",
encoder_weights="imagenet",
in_channels=1,
classes=3,
)The object you get back is an ordinary torch.nn.Module, so it goes straight into a standard training loop. If you want to match the encoder's pretraining, the README gives a second snippet for that.
from segmentation_models_pytorch.encoders import get_preprocessing_fn
preprocess_input = get_preprocessing_fn('resnet18', pretrained='imagenet')Note the mismatch in the README itself: the model example uses resnet34 while the preprocessing example uses resnet18. Pass the same encoder name to both or the normalization will not correspond to the weights you loaded. The repository also carries runnable notebooks under examples/, including binary_segmentation_intro.ipynb for OxfordPets and camvid_segmentation_multiclass.ipynb, plus pretrained inference notebooks for Segformer, DPT and UPerNet. Those are the fastest way to see a full loop rather than a bare model.
Where SMP stops: no training loop, no 3D, and an unclear upgrade path
The library is deliberately narrow, and that narrowness is the main limitation. Losses and metrics are listed as a feature (Dice, Jaccard, Tversky and others), but the README's own closing line for the quick start is "Now you can train your model with your favorite framework", which is a clear statement that training orchestration is out of scope. If you want checkpointing, distributed training, schedulers or experiment tracking, you supply them.
A second boundary is dimensionality. The API is built around in_channels and classes, and the examples are all 2D image datasets. Nothing in the README or the repository layout indicates volumetric segmentation support, so medical or geospatial work on 3D volumes is a poor fit; you would be reshaping volumes into 2D slices and losing inter-slice context.
A third issue is version drift. The pyproject.toml declares torch>=1.11, while the README badge advertises PyTorch 1.9+. The README does not document a migration guide between releases, and the release list shows v0.3.4, v0.4.0 and v0.5.0 across roughly eight months, which means minor-version upgrades are frequent enough to matter. The Makefile's test target runs pytest with --non-marked-only, and the pytest configuration defines logits_match, compile, torch_export and torch_script markers, so numerically significant tests sit behind markers that the default run skips. If you are upgrading in production, run the full suite rather than the default one.
How SMP differs from training your own backbone with torchvision or timm
The closest alternative is not another segmentation library but assembling the pieces yourself: take a torchvision or timm backbone, cut it at the feature-map boundaries, and write your own decoder and skip connections. That approach gives you complete control over where features are tapped and how they are fused, and it avoids a dependency layer. It also means reimplementing Unet++ nested skip pathways, FPN lateral connections, or the DPT reassemble-and-fuse stages, each of which has details that are easy to get subtly wrong.
SMP's trade is the reverse: you accept its construction of those architectures and its encoder naming scheme, and in exchange you get 12 architectures that already match their published designs, plus a uniform way to swap encoders. The practical difference shows up when you want a nonstandard decoder. SMP exposes model construction, not decoder internals, so a genuinely novel fusion block means subclassing or dropping to timm. For standard Unet, Unet++, FPN, PSPNet, DeepLabV3, DeepLabV3+, PAN, MAnet, Linknet, UPerNet, Segformer or DPT, SMP is the shorter path. The repository also supports ONNX export and is described as torch script, trace and compile friendly, with examples/convert_to_onnx.ipynb and a save/load notebook for the Hugging Face Hub, which covers the deployment step that a hand-rolled backbone would leave to you.
Maintenance, licence and what an upgrade actually costs
The repository is not archived, and the last push was on 2026-09-15, so the project is under current development. Releases are not on a fixed cadence: v0.3.4 in 2024-08, v0.4.0 in 2025-01 and v0.5.0 in 2025-04. The gap between v0.4.0 and v0.5.0 is under four months, which suggests minor releases can carry behavioural changes, and the README does not document rollback or a deprecation policy. Pin the version in your requirements and read the release notes before moving.
The licence is MIT, declared both in the repository metadata and in the pyproject.toml license field with license-files = ["LICENSE"]. There is a licenses/ directory in the repository, which is worth reading because the encoder weights SMP downloads are not necessarily covered by the same terms as the library code. That is a factual observation about the repository layout, not legal advice; check the terms attached to the specific pretrained weights you use.
The upgrade cost is dominated by the dependency floor rather than by SMP's own code. torch>=1.11, torchvision>=0.12 and timm>=0.9 move together, and timm in particular governs which encoder names resolve. A timm upgrade can rename or retire an encoder string that your config depends on, and SMP will fail at model construction time rather than at import time. The repository's Makefile provides install_dev to install the package with its test extras, and test_all with RUN_SLOW=1 to include the slow tests, which is the check to run before trusting a version bump.
Editorial conclusion
Adopt segmentation_models_pytorch if you already have a PyTorch training loop and want a decoder head attached to a pretrained encoder, and if your data is 2D. Do not adopt it expecting a training framework, a 3D pipeline, or a web service; the library builds torch.nn.Module objects and stops there. Before committing, verify that your chosen encoder name appears in the encoder table in the docs, that get_preprocessing_fn returns the normalization your encoder was pretrained with, and that your installed torch version satisfies the torch>=1.11 floor in pyproject.toml, since the README badge advertises an older PyTorch 1.9+.
Frequently asked questions
How do I install segmentation_models_pytorch?
Install it from PyPI with pip install segmentation-models-pytorch. The package requires Python 3.10 or newer and pulls in torch, torchvision, timm, numpy, pillow, safetensors, huggingface-hub and tqdm as dependencies.
What is segmentation_models_pytorch?
It is a Python library built on PyTorch that provides 12 encoder-decoder architectures for image semantic segmentation, together with 800+ pretrained convolution and transformer encoders. The models it returns are standard torch.nn.Module objects, so training orchestration is left to you.
Which encoders can I use with segmentation_models_pytorch?
The README lists 800+ pretrained convolution and transformer encoders, including timm support, and points to an encoder table in the documentation. The repository description gives 500+ instead, so check the docs table for the specific encoder name you plan to pass to encoder_name.
Does segmentation_models_pytorch work for 3D segmentation?
The documented API is built around in_channels and classes and every example in the repository is a 2D image dataset. Nothing in the README or repository layout indicates volumetric support, so 3D volumes are outside what the material describes.
What losses does segmentation_models_pytorch provide?
The README lists popular metrics and losses for training routines, naming Dice, Jaccard and Tversky among them. The exact set is not enumerated in the README, so consult the documentation for the full list before assuming a specific loss exists.
Community notes