PyTorch · Class

nn.ModuleList

ModuleList stores child modules in a list-like container while registering them with the parent module. It supports indexed access and iteration, but the enclosing module controls how the children are executed.

How it works

ModuleList is a container for child modules that behaves like a Python list while registering those children with the parent module. It is useful when a model needs indexed or iterative access but must define its own forward computation.

Syntax

class torch.nn.modules.container.ModuleList(*modules=None*)

Parameters

Name	Type	Description
`modules`	`iterable`	Optional iterable of modules to add initially.

Returns

A ModuleList container; append, extend, and insert return Self as documented for those methods.

Key points

Use ModuleList to keep several child modules together while retaining list-like organization.
Contained modules participate in the parent module's registration and are visible to Module APIs.
Registration lets standard Module operations account for the children rather than treating them as untracked objects.
append adds one nn.Module after the current final element.
extend adds multiple modules supplied by an iterable.
insert places one module before the selected integer index.

Common mistakes

It supports list-style indexing, but it does not define how the contained modules are executed; the parent module must call them in forward.

Example: Iterate over registered layers

import torch
from torch import nn

class BlockStack(nn.Module):
    def __init__(self):
        super().__init__()
        self.layers = nn.ModuleList([
            nn.Linear(4, 4),
            nn.ReLU(),
            nn.Linear(4, 2),
        ])

    def forward(self, x):
        for layer in self.layers:
            x = layer(x)
        return x

model = BlockStack()
print(model(torch.randn(3, 4)).shape)

Stores heterogeneous layers while explicitly controlling their execution order.

When to use it

Dynamic layer collections

A model has a variable number of repeated or heterogeneous layers that should remain registered as children.

Custom execution paths

Forward computation needs indexing, loops, branching, or custom combinations instead of fixed sequential execution.

Mutable architecture assembly

Modules are added or reordered after container construction.

Interview questions

QWhy use ModuleList instead of a normal Python list?

ModuleList stores child modules in an indexed, list-like container. Unlike ordinary Python lists, its children are registered, so Module methods can discover and manage them.

Follow-up: What happens if layers must be applied automatically in sequence? Use Sequential when its built-in sequential behavior matches the architecture; ModuleList is preferable when forward needs custom control.

QHow can modules be populated and accessed?

Construct it with an optional iterable of modules, then access elements by integer index or iterate over them. You can also add modules later with append, extend, or insert.

Follow-up: How would you add one module at a specific position? Call insert(index, module), which places the module before the specified index.

QDoes ModuleList automatically run its modules?

ModuleList itself is a container and does not specify a computation graph. The enclosing Module's forward method decides whether to iterate, select by index, branch, or combine its contained modules.

Follow-up: How can you implement a depth-dependent path? Select or iterate over the required indices in forward, while keeping all candidate modules registered in the ModuleList.

torch.nn.Module
torch.nn.Sequential
append
extend
insert

Source: ModuleList — PyTorch main documentation. Checked 2026-10-16.