How to Use _repr_mimebundle_ in Jupyter Notebook

In the previous post, we explored the different types of repr methods available in Jupyter Notebook.

What is the _repr_mimebundle_ Method?

The _repr_mimebundle_ method is a powerful feature in Jupyter Notebook that handles multiple MIME types and allows the notebook to automatically select and render the most appropriate format. If none of the repr methods are available, Jupyter falls back to Python’s built-in __repr__ or __str__ methods.

In Jupyter’s method resolution order, _repr_mimebundle_ is called second, making it a versatile choice for providing multiple output formats from a single method.

Creating a Custom _repr_mimebundle_ Method

Let’s start with a simple example that defines a custom _repr_mimebundle_ representation for a Person class:

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age
    
    def generate_html(self):
        return f"""
        <div style="border:1px solid #ddd; padding:10px; max-width:300px; border-radius:8px;">
            <h3>{self.name}</h3>
            <p><strong>Age:</strong> {self.age}</p>
        </div>
        """
    
    def generate_markdown(self):
        return f"## {self.name}\n- **Age:** {self.age}"
    def _repr_mimebundle_(self, include=None, exclude=None):
        return {
            "text/html": self.generate_html(),
            "text/markdown": self.generate_markdown(),
        }
new_person = Person("Alice", 30)
new_person

Output: The output will display as HTML because Jupyter Notebook prioritizes HTML over Markdown. This priority is handled internally by IPython’s core module.

Understanding include and exclude Parameters

The _repr_mimebundle_ method accepts two important parameters: include and exclude. To utilize these parameters effectively, you need to use the display method from the IPython module.

Here’s how to restrict MIME types using the exclude parameter:

from IPython.display import display
class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age
    
    def generate_html(self):
        return f"""
        <div style="border:1px solid #ddd; padding:10px; max-width:300px; border-radius:8px;">
            <h3>{self.name}</h3>
            <p><strong>Age:</strong> {self.age}</p>
        </div>
        """
    
    def generate_markdown(self):
        return f"## {self.name}\n- **Age:** {self.age}"
    def _repr_mimebundle_(self, include=None, exclude=None):
        mime_obj = {}
        if exclude is None:
            exclude = []
        
        if 'text/html' not in exclude:
            mime_obj["text/html"] = self.generate_html()
            
        if 'text/markdown' not in exclude:
            mime_obj["text/markdown"] = self.generate_markdown()
        
        return mime_obj
new_person = Person("Alice", 30)
display(new_person, exclude=['text/html'])

Now you’ll see the Markdown content rendered instead of HTML, because we explicitly excluded the HTML MIME type.

Global Configuration: Disabling Specific MIME Types

You might wonder how to configure this globally to affect all outputs in your Jupyter Notebook. Jupyter provides a way to enable or disable specific formatters.

Attempting to Disable the HTML Formatter

from IPython import get_ipython
ip = get_ipython()
# Disable HTML formatter globally
ip.display_formatter.formatters['text/html'].enabled = False

Important Note: If you test this with our Person class that uses _repr_mimebundle_, you’ll notice it doesn’t work as expected. This is because the enable/disable functionality only works with Jupyter’s built-in _repr_*_ methods (like _repr_html_, _repr_markdown_, etc.), not with custom _repr_mimebundle_ implementations.

Working Example with Separate _repr_ Methods

To make the global disable/enable functionality work, you need to use separate _repr_*_ methods:

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age
    
    def generate_html(self):
        return f"""
        <div style="border:1px solid #ddd; padding:10px; max-width:300px; border-radius:8px;">
            <h3>{self.name}</h3>
            <p><strong>Age:</strong> {self.age}</p>
        </div>
        """
    
    def generate_markdown(self):
        return f"## {self.name}\n- **Age:** {self.age}"
    def _repr_html_(self):
        return self.generate_html()
    def _repr_markdown_(self):
        return self.generate_markdown()
new_person = Person("Alice", 30)
new_person

With the HTML formatter disabled (as shown above), the output will render as Markdown instead of HTML. You can re-enable it anytime, and HTML will be rendered again.

Real-World Example: sklearn Models

Let’s examine how this works with scikit-learn models, which use HTML rendering by default:

from sklearn.linear_model import LinearRegression
model = LinearRegression()
model

Even with text/html formatter disabled, you’ll still see HTML output. Why? Because scikit-learn’s LinearRegression uses _repr_mimebundle_ internally.

Technical Insight: The LinearRegression class inherits from LinearModel, which inherits from BaseEstimator, which in turn inherits from ReprHTMLMixin. While _repr_html_ is defined in ReprHTMLMixin, the class also implements _repr_mimebundle_.

LinearRegression > LinearModel > BaseEstimator > ReprHTMLMixin > _repr_mimebundle_

According to Jupyter’s method resolution order, _repr_mimebundle_ is called first. If other repr methods exist, they are called as well, but the output follows a FIFO (First In, First Out) principle for display priority. This is why the global formatter disable doesn’t affect sklearn’s output.

Best Practices for _repr_mimebundle_

1. Handle Parameters Properly

Always check for include and exclude parameters:

def _repr_mimebundle_(self, include=None, exclude=None):
    data = {
        'text/html': self.generate_html(),
        'text/plain': str(self),
        'text/markdown': self.generate_markdown()
    }
    
    # Apply include filter
    if include is not None:
        data = {k: v for k, v in data.items() if k in include}
    
    # Apply exclude filter
    if exclude is not None:
        data = {k: v for k, v in data.items() if k not in exclude}
    
    return data

2. Provide Multiple Formats

Offer multiple MIME types to ensure compatibility across different Jupyter frontends and Keep your code clean by creating reusable filter methods.

def _filter_bundle(self, bundle, include=None, exclude=None):
    if include is not None:
        bundle = {k: v for k, v in bundle.items() if k in include}
    if exclude is not None:
        bundle = {k: v for k, v in bundle.items() if k not in exclude}
    return bundle
def _repr_mimebundle_(self, include=None, exclude=None):
    bundle = {
        'text/html': self.generate_html(),      # For Jupyter Notebook
        'text/plain': self.generate_plain(),    # Fallback
        'application/json': self.to_json()      # For specialized viewers
    }
    return self._filter_bundle(bundle, include, exclude)

Conclusion

The _repr_mimebundle_ method is a powerful tool for controlling how your Python objects are displayed in Jupyter Notebook. By mastering _repr_mimebundle_, you can create more interactive and visually appealing outputs in your Jupyter Notebooks, making your data science and analysis work more engaging and professional.

👉 In the next post, we’ll explore how to create custom repr methods and extend Jupyter’s display system with your own MIME types.

References:

1. https://wearexplorer.com/2025/10/20/understanding-python-repr-method/
2. https://wearexplorer.com/2025/10/21/mastering-jupyters-special-repr-methods-part-1/
3. https://wearexplorer.com/2025/10/22/mastering-jupyters-special-repr-methods-part-2/

👋