docs/deepnote-format.md
Rama main · réplica de lectura del repositorio original.
---
title: Introduction to Deepnote YAML file format
description: Learn about the Deepnote file format, its structure, and key differences from Jupyter notebooks.
noIndex: false
noContent: false
---
# Introduction to Deepnote YAML file format, and difference between Deepnote & Jupyter
Deepnote uses a human-readable YAML format (`.deepnote` files) to store notebooks and projects. This format is designed to be version-control friendly, easily readable, and extensible while maintaining compatibility with the Jupyter ecosystem.
## What is a `.deepnote` file?
A `.deepnote` file is a YAML-formatted document that holds a single notebook together with its project context, including:
- **Project metadata** (creation date, modification date, version)
- **The notebook** with its blocks and execution state
- **Project settings** (environment configuration, dependencies, integrations)
- **Execution modes** and working directories
Unlike Jupyter's JSON-based `.ipynb` format, Deepnote's YAML format prioritizes human readability and git-friendly diffs, making collaboration and version control significantly easier.
## File structure overview
A typical `.deepnote` file has the following top-level structure:
```yaml
metadata:
createdAt: "2025-01-27T12:00:00Z"
modifiedAt: "2025-01-27T14:30:00Z"
exportedAt: "2025-01-27T15:00:00Z"
checksum: "abc123..."
version: "1.0.0"
project:
id: "project-uuid"
name: "My Data Analysis Project"
initNotebookId: "notebook-uuid"
notebooks:
- id: "notebook-uuid"
name: "Analysis Notebook"
blocks: [...]
executionMode: "block"
isModule: false
workingDirectory: "/work"
integrations:
- id: "integration-uuid"
name: "Snowflake Connection"
type: "snowflake"
settings:
environment:
pythonVersion: "3.11"
customImage: "my-custom-image:latest"
requirements:
- "pandas>=2.0.0"
- "numpy>=1.24.0"
sqlCacheMaxAge: 3600
```
## Key components
### Metadata section
The metadata section contains file-level information:
- **`createdAt`**: ISO 8601 timestamp of when the project was created
- **`modifiedAt`**: ISO 8601 timestamp of the last modification
- **`exportedAt`**: ISO 8601 timestamp of when the file was exported
- **`checksum`**: Optional hash for file integrity verification
### Version
The `version` field specifies the Deepnote file format version (e.g., `'1.0.0'`). This ensures backward compatibility as the format evolves.
### Project section
The project section is the core of the file, containing:
#### Project properties
- **`id`**: Unique identifier for the project
- **`name`**: Human-readable project name
- **`initNotebookId`**: Optional ID of the notebook to open by default
#### Notebooks array
Each notebook in the project contains:
- **`id`**: Unique identifier for the notebook
- **`name`**: Notebook name
- **`blocks`**: Array of blocks (code, markdown, SQL, charts, etc.)
- **`executionMode`**: Either `'block'` (execute individual blocks) or `'downstream'` (execute dependent blocks)
- **`isModule`**: Boolean indicating if the notebook is a reusable module
- **`workingDirectory`**: Optional working directory path (defaults to `/work`)
#### Integrations array
Connected data sources and external services:
- **`id`**: Integration identifier
- **`name`**: Human-readable integration name
- **`type`**: Integration type (e.g., `'snowflake'`, `'bigquery'`, `'postgres'`)
#### Settings object
Project-wide configuration:
- **`environment`**: Python version and custom Docker images
- **`requirements`**: Python package dependencies
- **`sqlCacheMaxAge`**: SQL query cache duration in seconds
### Block structure
Each block in a notebook has the following structure:
```yaml
- id: "block-uuid"
type: "code" # or 'markdown', 'sql', 'chart', 'input', etc.
sortingKey: "1"
blockGroup: "group-uuid"
content: |
import pandas as pd
df = pd.read_csv('data.csv')
df.head()
executionCount: 1
version: 1
metadata:
custom_field: "value"
outputs:
- output_type: "execute_result"
data:
text/plain: "..."
```
**Block properties:**
- **`id`**: Unique block identifier
- **`type`**: Block type (`'code'`, `'markdown'`, `'sql'`, `'chart'`, `'input'`, etc.)
- **`sortingKey`**: Base-36 encoded position for ordering blocks
- **`blockGroup`**: Optional grouping identifier for related blocks
- **`content`**: The actual code, markdown, or query content
- **`executionCount`**: Number of times the block has been executed
- **`version`**: Block schema version
- **`metadata`**: Arbitrary key-value pairs for block-specific settings
- **`outputs`**: Array of execution outputs (for code and SQL blocks)
## Deepnote vs. Jupyter: Key differences
While Deepnote maintains compatibility with Jupyter, there are important differences:
### File format
| Feature | Jupyter (`.ipynb`) | Deepnote (`.deepnote`) |
| --------------------- | --------------------- | ---------------------- |
| **Format** | JSON | YAML |
| **Readability** | Machine-optimized | Human-optimized |
| **Git diffs** | Noisy, hard to review | Clean, easy to review |
| **File organization** | One file per notebook | One notebook per file |
| **Project settings** | Not included | Included in file |
### Project-level organization
**Jupyter:**
- Each notebook is a separate `.ipynb` file
- No native project concept
- Dependencies managed separately (e.g., `requirements.txt`)
- No built-in integration management
**Deepnote:**
- Each notebook lives in its own `.deepnote` file
- Dependencies and settings embedded in the file
- Integration configurations included
- Module system for reusable notebooks
### Block types
**Jupyter:**
- Code cells (Python, R, Julia, etc.)
- Markdown cells
- Raw cells
**Deepnote:**
- All Jupyter cell types supported
- **Additional block types:**
- SQL blocks with native database connectivity
- Chart blocks with visual query builder
- Input blocks for interactive parameters
- Big number blocks for KPIs
- Rich text blocks with advanced formatting
### Execution modes
**Jupyter:**
- Sequential execution only
- Cells executed in order or individually
**Deepnote:**
- **Block mode**: Execute blocks independently
- **Downstream mode**: Automatically execute dependent blocks
- Dependency tracking between blocks
### Metadata and settings
**Jupyter:**
```json
{
"metadata": {
"kernelspec": {
"name": "python3",
"display_name": "Python 3"
}
}
}
```
**Deepnote:**
```yaml
project:
settings:
environment:
pythonVersion: "3.11"
customImage: "custom-image:latest"
requirements:
- "pandas>=2.0.0"
sqlCacheMaxAge: 3600
```
### Output storage
**Jupyter:**
- Outputs embedded in notebook JSON
- Can make files very large
- Binary data base64-encoded
**Deepnote:**
- Outputs stored in YAML format
- Cleaner representation
- Better for version control
- Optional output persistence
## Converting between formats
For detailed instructions on converting between Jupyter notebooks and Deepnote format, see the [Converting Notebooks guide](/docs/converting-notebooks).
## Example of a complete Deepnote file
Here's a minimal but complete example:
```yaml
metadata:
createdAt: "2025-01-27T12:00:00Z"
version: "1.0.0"
project:
id: "abc-123-def-456"
name: "Sales Analysis"
notebooks:
- id: "notebook-001"
name: "Q4 Analysis"
executionMode: "block"
isModule: false
blocks:
- id: "block-001"
type: "markdown"
sortingKey: "1"
content: |
# Q4 Sales Analysis
This notebook analyzes sales data for Q4 2024.
version: 1
metadata: {}
- id: "block-002"
type: "code"
sortingKey: "2"
content: |
import pandas as pd
df = pd.read_csv('sales_q4.csv')
print(f"Total rows: {len(df)}")
executionCount: 1
version: 1
metadata: {}
outputs:
- output_type: "stream"
name: "stdout"
text: 'Total rows: 1523\n'
integrations: []
settings:
environment:
pythonVersion: "3.11"
requirements:
- "pandas>=2.0.0"
```
## Resources
- [Deepnote GitHub repository](https://github.com/deepnote/deepnote)
- [@deepnote/convert package](https://www.npmjs.com/package/@deepnote/convert)
- [Deepnote file schema](https://github.com/deepnote/deepnote/blob/main/packages/blocks/src/deepnote-file/deepnote-file-schema.ts)