0
# Notebook Integration
1

2
TensorBoard provides utilities for seamless integration with interactive notebook environments including Jupyter notebooks and Google Colab. The notebook module automatically detects the runtime environment and provides appropriate display methods for each context.
3

4
## Capabilities
5

6
### TensorBoard Launch
7

8
Start a TensorBoard instance from within a notebook environment with automatic context detection.
9

10
```python { .api }
11
def start(args_string):
12
    """
13
    Launch TensorBoard in notebook environment.
14
    
15
    Args:
16
        args_string (str): Command-line arguments as a single string
17
                          (same format as tensorboard CLI)
18
    
19
    Automatically detects and handles:
20
    - Google Colab environments
21
    - Jupyter notebook environments  
22
    - IPython shell environments
23
    - Standard CLI environments
24
    """
25
```
26

27
### TensorBoard Display
28

29
Display a running TensorBoard instance within the notebook interface.
30

31
```python { .api }
32
def display(port=None, height=None):
33
    """
34
    Display running TensorBoard instance in notebook.
35
    
36
    Args:
37
        port (int, optional): TensorBoard server port. If None, attempts
38
                             to auto-detect running instance
39
        height (int, optional): Frame height in pixels (default 800)
40
    
41
    Provides environment-specific display:
42
    - Colab: Embedded iframe with proxy URL handling
43
    - Jupyter: Local iframe integration
44
    - CLI: Prints URL for manual access
45
    """
46
```
47

48
### Instance Management
49

50
List and manage running TensorBoard instances.
51

52
```python { .api }
53
def list():
54
    """
55
    List all known running TensorBoard instances.
56
    
57
    Returns:
58
        Information about active TensorBoard processes including
59
        ports, PIDs, start times, and data sources
60
    """
61
```
62

63
### IPython Extension Loading
64

65
Integration with IPython's extension system for magic commands.
66

67
```python { .api }
68
def load_ipython_extension(ipython):
69
    """
70
    Deprecated: use '%load_ext tensorboard' instead.
71
    
72
    Args:
73
        ipython: IPython.InteractiveShell instance
74
        
75
    Raises:
76
        RuntimeError: Always, directing users to correct usage
77
    """
78
```
79

80
## Usage Examples
81

82
### Basic Notebook Usage
83

84
```python
85
import tensorboard.notebook as tb_notebook
86

87
# Launch TensorBoard with log directory
88
tb_notebook.start('--logdir ./logs')
89

90
# Display in notebook (auto-detects port)
91
tb_notebook.display()
92
```
93

94
### Advanced Configuration
95

96
```python
97
import tensorboard.notebook as tb_notebook
98

99
# Launch with multiple options
100
tb_notebook.start('--logdir ./experiments --port 6007 --reload_interval 30')
101

102
# Display with custom height
103
tb_notebook.display(port=6007, height=1000)
104

105
# List running instances
106
running_instances = tb_notebook.list()
107
print(f"Found {len(running_instances)} TensorBoard instances")
108
```
109

110
### IPython Magic Commands
111

112
After loading the TensorBoard extension, magic commands become available:
113

114
```python
115
# Load the extension (run once per session)
116
%load_ext tensorboard
117

118
# Use magic command to launch TensorBoard
119
%tensorboard --logdir ./logs --port 6006
120
```
121

122
### Environment-Specific Behavior
123

124
The notebook module automatically adapts to different environments:
125

126
**Google Colab:**
127
- Uses Colab's proxy system for secure external access
128
- Handles authentication and URL rewriting automatically
129
- Displays TensorBoard in embedded iframe
130

131
**Jupyter Notebook:**
132
- Creates local iframe pointing to TensorBoard server
133
- Handles port forwarding if needed
134
- Integrates with Jupyter's display system
135

136
**IPython/CLI:**
137
- Prints clickable URLs for manual browser access
138
- Provides terminal-friendly output formatting
139
- Maintains compatibility with non-browser environments
140

141
### Context Detection
142

143
The module uses the following detection logic:
144

145
1. **Colab Detection**: Checks for `google.colab` module and IPython kernel
146
2. **Jupyter Detection**: Checks for IPython instance with `kernel` trait
147
3. **CLI Fallback**: Falls back to command-line behavior for other environments
148

149
This ensures TensorBoard works consistently across different development environments while providing the best possible user experience for each context.