0
# Jupyter
1

2
The Jupyter metapackage provides a single installation point for the complete Jupyter ecosystem. Rather than containing functional code, it serves as a convenience package that installs and coordinates multiple core Jupyter components, simplifying setup for end users who want a complete interactive computing environment.
3

4
## Package Information
5

6
- **Package Name**: jupyter
7
- **Package Type**: Python metapackage
8
- **Language**: Python (packaging only)
9
- **Installation**: `pip install jupyter`
10
- **Version**: 1.1.1
11

12
## Core Imports
13

14
The Jupyter metapackage itself contains no Python modules and provides no importable code:
15

16
```python
17
# ❌ This will fail - jupyter metapackage has no modules
18
import jupyter  # ModuleNotFoundError
19
```
20

21
Instead, import from the individual components it installs:
22

23
```python
24
# ✅ Import from installed components
25
from notebook import notebookapp
26
from jupyter_console import app
27
from nbconvert import HTMLExporter
28
from IPython.display import display
29
from ipywidgets import interact
30
```
31

32
## Basic Usage
33

34
The metapackage is used for installation only. After installation, use the individual Jupyter components:
35

36
```bash
37
# Install all Jupyter components at once
38
pip install jupyter
39

40
# Launch Jupyter Notebook
41
jupyter notebook
42

43
# Launch JupyterLab
44
jupyter lab
45

46
# Launch Jupyter Console
47
jupyter console
48

49
# Convert notebooks
50
jupyter nbconvert notebook.ipynb --to html
51
```
52

53
## Architecture
54

55
The Jupyter metapackage uses a dependency-only approach where:
56

57
- **No modules**: Contains zero Python code (`py_modules = []`)
58
- **Dependency aggregation**: Declares `install_requires` dependencies on core components
59
- **User convenience**: Provides single command installation of complete Jupyter environment
60
- **Not for libraries**: Should never be used as a dependency by other packages
61

62
## Capabilities
63

64
### Installation Management
65

66
The metapackage installs these core Jupyter components when you run `pip install jupyter`:
67

68
```python { .api }
69
# Dependency declarations in setup.py (not importable functions)
70
install_requires = [
71
    'notebook',           # Jupyter Notebook application
72
    'jupyter-console',    # Terminal-based Jupyter client  
73
    'nbconvert',         # Convert notebooks between formats
74
    'ipykernel',         # IPython kernel for Jupyter
75
    'ipywidgets',        # Interactive widgets for notebooks
76
    'jupyterlab',        # Modern web-based Jupyter interface
77
]
78
```
79

80
### Component Access
81

82
After installation via the metapackage, access individual components through CLI commands:
83

84
```bash { .api }
85
# Jupyter Notebook
86
jupyter notebook
87
# Launch Jupyter Notebook server interface
88

89
# JupyterLab  
90
jupyter lab
91
# Launch modern JupyterLab web interface
92

93
# Jupyter Console
94
jupyter console
95
# Launch terminal-based interactive Jupyter session
96

97
# Notebook Conversion
98
jupyter nbconvert <source_file> --to <target_format>
99
# Convert notebooks between different formats (html, pdf, etc.)
100
```
101

102
### Usage Patterns
103

104
The metapackage follows specific usage patterns:
105

106
```text { .api }
107
# ✅ Recommended: End-user installation
108
pip install jupyter
109
# Provides complete Jupyter environment in single command
110
# Installs all core components: notebook, jupyterlab, console, etc.
111

112
# ❌ Not recommended: Package dependency  
113
# setup.py: install_requires=['jupyter']  # DON'T DO THIS
114
# Other packages should NOT depend on jupyter metapackage
115
# Instead depend on specific components like 'notebook' or 'jupyterlab'
116

117
# ✅ Recommended: Component-specific dependencies
118
# setup.py examples for libraries:
119
# install_requires=['notebook>=6.0']      # for notebook server integration
120
# install_requires=['ipykernel>=5.0']     # for kernel development  
121
# install_requires=['nbconvert>=6.0']     # for notebook processing
122
# install_requires=['ipywidgets>=7.0']    # for interactive widgets
123
```
124

125
## Installation Behavior
126

127
When installing the Jupyter metapackage:
128

129
1. **Dependency Resolution**: pip installs all components listed in `install_requires`
130
2. **Command Registration**: Each component registers its CLI commands (`jupyter notebook`, `jupyter lab`, etc.)
131
3. **No Module Installation**: No `jupyter` module is created - only dependencies are installed
132
4. **Environment Setup**: Complete Jupyter environment becomes available for immediate use
133

134
## Error Handling
135

136
Common issues when using the metapackage incorrectly:
137

138
```python { .api }
139
# ImportError: No module named 'jupyter'
140
import jupyter  # ❌ This will fail!
141
# ModuleNotFoundError: No module named 'jupyter'
142

143
# ✅ Correct approach - import from installed components:
144
from notebook import notebookapp
145
from jupyter_console import app  
146
from IPython.display import display
147
from ipywidgets import interact
148
```
149

150
```text { .api }
151
# Dependency conflicts in setup.py
152
install_requires = ['jupyter']  # ❌ Can cause version conflicts
153

154
# ✅ Better approach - use specific components:
155
install_requires = [
156
    'notebook>=6.0',     # instead of 'jupyter'
157
    'ipykernel>=5.0'     # for kernel functionality
158
]
159
```
160

161
## Migration Notes
162

163
For packages currently depending on the jupyter metapackage:
164

165
```text { .api }
166
# setup.py migration example:
167

168
# Before (problematic):
169
install_requires = ['jupyter']
170

171
# After (recommended):
172
install_requires = [
173
    'notebook>=6.0',     # for notebook server functionality
174
    'ipykernel>=5.0'     # for kernel development
175
]
176

177
# This provides better dependency resolution and clearer requirements
178
```