Install & Compatibility
Where this runs
tested against v0.0.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
4787MB installed
● package 4787MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
make_dot
✓ from torchviz import make_dot
This is the primary function for visualizing computational graphs from a PyTorch Variable.
make_dot_from_trace
✓ from torchviz import make_dot_from_trace
✗ from torchviz import make_dot_from_trace
While available, `make_dot_from_trace` using `torch.jit.trace` is noted to be less reliable and 'does not always work', especially with newer PyTorch versions. Prefer `make_dot` for general use.
This quickstart defines a simple PyTorch neural network, performs a forward pass with an input tensor that requires gradients, and then uses `make_dot` to generate and optionally save a visualization of the computational graph. Ensure Graphviz is installed on your system for rendering.
import torch
import torch.nn as nn
from torchviz import make_dot
# Define a simple neural network
class SimpleNN(nn.Module):
def __init__(self):
super(SimpleNN, self).__init__()
self.fc1 = nn.Linear(10, 5)
self.fc2 = nn.Linear(5, 1)
def forward(self, x):
x = torch.relu(self.fc1(x))
x = self.fc2(x)
return x
# Instantiate the model
model = SimpleNN()
# Generate a random input, ensuring requires_grad=True for graph generation
input_data = torch.randn(1, 10, requires_grad=True)
# Perform a forward pass
output = model(input_data)
# Visualize the computational graph
graph = make_dot(output, params=dict(model.named_parameters()))
# To save the visualization to a file (e.g., PNG)
# graph.render("computational_graph", format="png", cleanup=True)
# In Jupyter/Colab, the graph can often be displayed directly by just calling it
# graph
Debug
Known issues
breakingTorchviz critically depends on the external Graphviz software package being installed on your operating system, not just the Python `graphviz` package. Without a system-wide Graphviz installation (e.g., `brew install graphviz` on macOS, `sudo apt-get install graphviz` on Ubuntu, or installing from graphviz.org for Windows), `make_dot` will not be able to render images, often failing silently or with obscure errors about missing executables.fixInstall Graphviz on your system using your operating system's package manager or by downloading from the official Graphviz website (graphviz.org).
affects: All versions
gotchaFor `make_dot` to generate a meaningful computational graph, at least one of the input tensors to the operation being visualized must have `requires_grad=True`. If no tensor requires a gradient, PyTorch's autograd engine (which `torchviz` inspects) won't track operations, resulting in an empty or incomplete graph.fixEnsure that the input tensor used in the forward pass has `requires_grad=True` (e.g., `torch.randn(..., requires_grad=True)`).
affects: All versions
deprecatedThe `make_dot_from_trace` function, intended for use with `torch.jit.trace`, is noted to be less robust and 'does not always work' according to the official documentation, especially with newer PyTorch versions. Past issues have reported it not working with PyTorch 1.0.fixPrefer using `make_dot` with the output of a forward pass and `model.named_parameters()` for reliable graph visualization.
affects: All versions, particularly problematic with PyTorch >= 1.0
gotchaThe `show_attrs=True` and `show_saved=True` parameters, which provide additional details about the graph nodes (attributes and saved tensors for the backward pass), are only supported with PyTorch versions 1.9 and later. Using them with older PyTorch versions might not have the intended effect or could lead to errors.fixEnsure your PyTorch installation is version 1.9 or higher to fully utilize `show_attrs` and `show_saved`. If using an older version, omit these parameters.
affects: <1.9
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'torchviz'
The `torchviz` package is not installed or not available in the current Python environment.
FileNotFoundError: [Errno 2] No such file or directory: 'dot'
The `torchviz` library uses the `graphviz` system tool, and the `dot` executable is not installed on your system or is not in your system's PATH.
fixInstall `graphviz` system-wide (e.g., `sudo apt-get install graphviz` on Ubuntu, `brew install graphviz` on macOS, or download the installer from graphviz.org for Windows) and ensure it's added to your system's PATH.
AttributeError: 'tuple' object has no attribute 'grad_fn'
The `make_dot` function was called with a tuple as its primary input (e.g., when a model returns multiple outputs), but it expects a single PyTorch tensor with a `grad_fn` attribute for graph tracing.
fixPass only the specific output tensor you want to visualize (e.g., `output[0]`) to `make_dot` if your model returns a tuple of tensors.
Upgrade
Version history
0.0.3latest on PyPI · released Dec 2, 2024
Audit
Dependencies
torchrequiredCore PyTorch functionality for model definition and execution graphs.
graphvizrequiredRequired for rendering the computational graphs; both the Python `graphviz` package and the system-level Graphviz binaries are necessary.