segmentation_models.pytorch: the encoder you name decides your weights, your preprocessing and your pin

Four keyword arguments and a plain torch.nn.Module

The quick start builds a model with four keywords. `encoder_name` selects the backbone, `encoder_weights` decides whether ImageNet initialization is fetched, `in_channels` sets the input tensor width, and `classes` sets the output tensor width. What comes back is an ordinary `torch.nn.Module`, with no base trainer class and no SMP specific runtime to learn.

import segmentation_models_pytorch as smp

model = smp.Unet(
    encoder_name="resnet34",        # choose encoder, e.g. mobilenet_v2 or efficientnet-b7
    encoder_weights="imagenet",     # use `imagenet` pre-trained weights for encoder initialization
    in_channels=1,                  # model input channels (1 for gray-scale images, 3 for RGB, etc.)
    classes=3,                      # model output channels (number of classes in your dataset)
)

What that call does not do is the larger half of a segmentation project. No dataset class, no dataloader, no optimizer, no schedule, no checkpoint resume and no evaluation loop live in the package. Dice, Jaccard and Tversky arrive as loss and metric functions for a training routine you write. Most entries under examples/ are notebooks you run and then edit, which fixes the boundary: SMP is a model factory, and the recipe stays in your repository.

get_preprocessing_fn will preprocess for a different encoder than the one you built

Preprocessing is a separate call, so nothing checks that the two encoder names agree. The quick start builds `smp.Unet(encoder_name="resnet34")` and then configures `get_preprocessing_fn('resnet18', pretrained='imagenet')`. Copy both snippets and you feed ResNet18 normalization into a ResNet34 encoder.

from segmentation_models_pytorch.encoders import get_preprocessing_fn

preprocess_input = get_preprocessing_fn('resnet18', pretrained='imagenet')

The stated consequence is that preparing data the way it was prepared during weight pre-training may give a higher metric score and faster convergence. The same note says that step is not necessary if you train the whole model and not only the decoder, which is the whole of the quick start's guidance on freezing. A mismatch raises nothing: no warning, no exception, and no config key in pyproject.toml links the two names.

The Makefile virtualenv target installs beside your interpreter, not in the checkout

Contributor setup is where the friction turns concrete. `PYTHON` and `PIP` are resolved once at parse time with `which`, and the `.venv` target hands `$(shell dirname $(PYTHON))` to `python -m venv`, which puts the new environment in the same directory as the interpreter itself.

PYTHON := $(shell which python)
PIP := $(shell which pip)

# Target to create a Python virtual environment
.venv:
	$(PYTHON) -m venv $(shell dirname $(PYTHON))

No target creates a `.venv` directory in your working copy, and nothing depends on one existing there. The outcome depends entirely on where your interpreter lives. When `which python` resolves into a prefix your user cannot write to, `make install_dev` fails on a permission error rather than a missing dependency, and the fix does not live in this Makefile. When it resolves into a user managed prefix, the target writes a second environment into that install prefix, where you will forget it. Meanwhile `PIP` came from its own `which pip`, so the editable install can land in a different environment from the `python` that pytest is later run through.

make test skips the compile, torch_export and torch_script markers

The default test target filters by marker, which is exactly where two advertised features are verified.

# Target to run tests with pytest, using 2 parallel processes and only non-marked tests
test: .venv
	$(PYTEST) -v -rsx -n 2 tests/ --non-marked-only

`compile`, `torch_export`, `torch_script` and `logits_match` are registered in pyproject.toml and all of them are excluded by `--non-marked-only`. Reaching the export paths means the `test_all` target with its `RUN_SLOW=1` variable:

RUN_SLOW=1 $(PYTEST) -v -rsx -n 2 tests/

A green `make test` therefore says nothing about the compile, torch_export and torch_script markers, which are the paths that matter when a trained model leaves Python. Run `test_all` to cover them. The coverage config makes the gap visible too: it omits `segmentation_models_pytorch/utils/*` and every `**/convert_*` module.

Encoder weights arrive at first use, and MIT does not travel with them

The dependency list explains where the pretrained part lives. `safetensors>=0.3.1`, `huggingface-hub>=0.24` and `timm>=0.9` are required at runtime rather than optional extras, and no wheel carries backbone weights. An encoder built with `encoder_weights="imagenet"` needs a reachable artifact store before its first forward pass. pyproject.toml configures no mirror, no local weight directory and no offline switch, so there is no knob in the package to turn when the training host has no route out. On a locked down network you are left hosting the cache yourself, with no documented procedure for doing it.

Licensing follows the same shape. This repository's own LICENSE is MIT, which covers the library code. The encoders do not fall under it: `timm>=0.9` and the torchvision backbones carry their own upstream terms, so a checkpoint you ship inherits conditions from whichever encoder you chose. Read the upstream terms for that specific encoder before a trained model goes into a product.

800+ encoders in one place, 500+ backbones in another

Two numbers describe the encoder catalogue and they disagree. The repository description says 500+ pretrained convolutional and transformer-based backbones, while the feature list says 800+ pretrained convolution and transform-based encoders, including timm support. The architecture table carries its own Checkpoints column, and that table is the honest answer to how many encoders exist.

It is generated, not hand written. Two Makefile targets produce it:

$(PYTHON) misc/generate_table.py
$(PYTHON) misc/generate_table_timm.py

`table` and `table_timm` are separate Makefile targets, and the second one is for timm encoders. Pin timm whenever you pin SMP, and read the regenerated table rather than either headline figure when you are sizing a benchmark.

Python 3.10, torch 1.11 and a PyPy classifier with nothing scoped to PyPy

`requires-python = '>=3.11'` sits above `torch>=2` and `torchvision>=0.15.1`, with `numpy>=1.23.2`, `pillow>=9.2` and `tqdm>=4.42.1` among the runtime dependencies. Classifiers name both CPython and PyPy, and the export and compile claims in the README are not scoped to an interpreter.

Version timing tells a second story. Releases are v0.4.0 on 2025-01-08, v0.5.0 on 2025-04-17 and v0.6.0 on 2026-10-26, and the last push was on 2026-11-02, days after that tag. Every example link in the README points at the main branch, so what you read there can be ahead of what pip installs. If you need the behaviour you are reading about, install from a tag and read that tag.

withoutBG sponsors the project and took smp.Unet somewhere else

The sponsor block at the top of the README is withoutBG, a background removal tool whose image matting and refiner models were built on smp.Unet. The examples table also lists the cloth segmentation work credited to @ternaus as a separate repository rather than a notebook.

If your output is an edge map, a depth map or a soft alpha, the head is where you start editing, and `classes` only tells you how many output channels you begin with. The README's table of contents lists three model API topics: input channels, auxiliary classification output, and depth. The full documentation is at https://smp.readthedocs.io/, built from docs/ by .readthedocs.yaml.

Editorial conclusion

SMP fits teams training a 2D semantic segmentation model on a single machine who want a pretrained encoder without writing the decoder themselves. It does not fit anyone who needs a training loop with checkpoint resume or an air-gapped install, because none of that ships in the package. Check the generated encoder table at https://smp.readthedocs.io/ rather than either headline count, confirm your encoder name matches your preprocessing call, and run `make test_all` instead of `make test`, since the default target skips the compile, torch_export and torch_script markers that cover the export path the README advertises.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. qubvel-org/segmentation_models.pytorch on GitHub
4. README
5. Releases