ResNet-34 from scratch

An educational implementation of ResNet-34 using PyTorch building blocks. The project follows the approach used in the ARENA CNNs & ResNets lesson: assemble the architecture ourselves, then transfer the official torchvision ImageNet-1K weights and verify that both models produce the same output.

The custom model does not wrap torchvision's ResNet. Torchvision is used as a temporary source for the official checkpoint, plus the preprocessing recipe and ImageNet class labels.

Architecture

The implementation is split into small modules that mirror the ResNet paper:

• BatchNorm2d, AveragePool, and Sequential provide the core operations.
• ResidualBlock implements two 3x3 convolutions and a skip connection.
• BlockGroup stacks residual blocks into the [3, 4, 6, 3] stages.
• ResNet34 combines the stem, four stages, global average pool, and classifier.

The resulting network has the canonical 21,797,672 parameters and emits 1,000 ImageNet class logits when pretrained weights are used.

Setup

Python 3.11 or newer is required. Create an isolated environment and install the project with its test dependencies:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev,pretrained]"

Inference

Pass either a local image or an HTTP(S) URL. On the first run, torchvision downloads the 83 MB checkpoint to PyTorch's standard cache directory.

python -m examples.run_inference \
  https://github.com/pytorch/hub/raw/master/images/dog.jpg

The model can also be used directly:

import torch
from resnet34 import ResNet34

model = ResNet34.from_pretrained()
with torch.inference_mode():
    logits = model(torch.randn(1, 3, 224, 224))

Use ResNet34(num_classes=...) for random initialization and a custom output size. Pretrained ImageNet weights require num_classes=1000.

Tests

pytest -q

The default suite checks individual module behavior, output shapes, parameter count, and state-loading validation without network access. To run the torchvision parity test, which downloads the pretrained checkpoint if needed, run:

pytest -q -m integration

The project can be installed without the optional pretrained workflow when only the randomly initialized model is needed:

python -m pip install -e "."

References

• Deep Residual Learning for Image Recognition
• ARENA: CNNs & ResNets
• torchvision ResNet source