Introduction

Adding images to Jupyter or IPython notebook markdown cells is straightforward, but reproducibility depends on how you reference those images. A notebook that renders correctly on one machine can break on another if paths are absolute, files are missing, or links require private network access.

A robust approach separates local project assets, remote URLs, and programmatic image generation. This guide covers all three patterns, including sizing control and version-friendly practices that work in shared repositories.

Core Sections

1) Standard Markdown syntax

Use Markdown image syntax for most static images.

![Model architecture](images/model-arch.png)

This is clean and portable when images/model-arch.png is committed with the notebook. Relative paths are usually better than absolute paths.

2) Control size with HTML in markdown cells

Markdown alone has limited sizing options, so HTML is often used.

<img src="images/confusion-matrix.png" alt="Confusion Matrix" width="500" />

This works in Jupyter markdown cells and gives exact control over width/height. Prefer width-only constraints to preserve aspect ratio.

3) Insert images hosted remotely

Remote URLs are useful for documentation generated elsewhere.

![Experiment dashboard](https://example.com/reports/run-42.png)

This keeps notebook size small, but rendering depends on network and permissions. For long-term reproducibility, archive critical images locally.

4) Display images from Python code cells

For dynamic workflows, render images programmatically.

1from IPython.display import Image, display
2
3display(Image(filename="images/training-loss.png", width=600))
4# or
5# display(Image(url="https://example.com/plot.png"))

This is useful when file names depend on run IDs or when images are generated during execution.

5) Use attachments for standalone notebooks

Some notebook frontends support markdown attachments so images are embedded in notebook JSON rather than separate files. This is convenient for single-file sharing, but can bloat notebook size in Git history. Use attachments for small diagrams, not large plots.

6) Reproducibility and repository structure

A good layout is:

1project/
2  notebooks/
3    analysis.ipynb
4  images/
5    analysis/
6      fig1.png

Then reference from notebook with relative paths like ../images/analysis/fig1.png if notebooks live in a subfolder. Add a brief “how to regenerate figures” section at the top of the notebook for teammates.

7) Production checklist for notebook image embedding

Treat this topic as an operational concern, not only a coding snippet. Start by defining one explicit success metric that reflects business behavior, such as failed request rate, pipeline lag, model quality drift, or user-visible latency. Then create a small acceptance checklist that can run in both staging and production-like test environments. The checklist should verify the happy path, at least one failure path, and one boundary case.

Capture configuration assumptions close to the implementation, including timeouts, versions, environment variables, and external dependencies. If behavior varies by environment, encode those differences in configuration rather than hardcoded branches. Add lightweight observability from day one: key counters, error categorization, and structured logs with identifiers that support correlation during incident response.

Finally, define rollback and ownership before rollout. Decide who responds to alerts, what threshold should trigger rollback, and which fallback mode keeps the system functional if this component degrades. A clear ownership and rollback plan turns isolated technical knowledge into a maintainable production practice.

Common Pitfalls

• Using absolute filesystem paths that only work on one developer machine.
• Linking private URLs that fail for reviewers or CI-rendered documentation.
• Embedding very large images as attachments and causing huge notebook diffs.
• Forgetting to commit image files referenced by markdown cells.
• Mixing inconsistent path conventions across notebooks in the same repository.

Summary

Image insertion in notebook markdown is easy, but durable notebooks require path discipline. Prefer relative paths for project assets, HTML when you need explicit sizing, and code-cell rendering for dynamic artifacts. Keep images organized in version-controlled directories and avoid environment-specific links. With that setup, your notebooks stay readable and reproducible across machines.