Databricks Repos serve as Git clients for Git-based source repositories, enabling you to perform a subset of Git operations on their contents. As part of this Git integration, files stored in the backing repo are viewed as “assets” based on their type, with some limitations in place specific to their type. Notebook files, in particular, have different properties based on their type. Read this article to understand how to work with assets, particularly IPYNB notebooks, in Databricks Repos.
When assets are pulled and pushed between a Databricks Git folder and the integrated Git repo, they are serialized and de-serialized, respectively. Serialization adds and updates metadata that the Databricks product uses to create asssociations that enables convenient functionality, like sharing generated visualizations and enabling simplified Git operations.
Only certain Databricks asset types are supported by Databricks Repos. In this case, “supported” means “can be serialized, version-controlled, and pushed to the backing Git repo.”
Currently, the supported asset types are:
Files are serialized data, and can include anything from libraries to binaries to code to images. For more information, read What are workspace files?
Notebooks are specifically the notebook file formats supported by Databricks. Notebooks are considered a separate Databricks asset type from Files since they are not serialized. Repos determines a Notebook by the file extension (such as
A folder is a Databricks-specific structure that represents serialized information about a logical grouping of files in Git. As expected, the user experiences this as a “folder” when viewing a Databricks Repo or accessing it with the Databricks CLI.
Potential Databricks asset types that are not supported in Databricks Repos today but may be supported in the future includes:
Dashboards (including Lakeview dashboards)
Databricks considers two kinds of high-level, Databricks-specific notebook formats: “source” and “ipynb”. When a user commits a notebook in the “source” format, the Databricks platform commits a flat file with a language suffix, such as
.r. A “source”-format notebook contains only source code and does not contain outputs such as table displays and visualizations that are the results of running the notebook.
The “ipynb” format, however, does have outputs associated with it, and those artifacts are automatically pushed to the Git repo backing the Git folder when pushing the
.ipynb notebook that generated them. If you want to commit outputs along with the code, use the “ipynb” notebook format and setup configuration to allow a user to commit any generated outputs. As a result, “ipynb” also supports a better viewing experience in Databricks for notebooks pushed to remote Git repos through Databricks Repos.
Notebook source format
Can be any code file with a standard file suffix that signals the code language, such as
“ipynb” files end with
If you want outputs pushed back to your repo after running a notebook, use a
.ipynb (Jupyter) notebook. If you just want to run the notebook and manage it in Git, use a “source” format like
For more details on supported notebook formats, read Export and import Databricks notebooks.
What are “outputs”?
Outputs are the results of running a notebook on the Databricks platform, including table displays and visualizations.
How do I tell what format a notebook is using, other than the file extension?
At the top of a notebook managed by Databricks, there is usually a single-line comment that indicates the format. For example, for a
.py “source” notebook, you will see a line that looks like this:
# Databricks notebook source
.ipynb files, the file suffix is used to indicate that it is the “ipynb” notebook format.
Support for Jupyter notebooks (
.ipynb files) is available in Databricks Repos. You can clone repositories with
.ipynb notebooks, work with them in the Databricks product, and then commit and push them as
.ipynb notebooks. Metadata such as the notebook dashboard is preserved. Admins can control whether outputs can be committed or not.
By default, the admin setting for Repos doesn’t allow
.ipynb notebook output to be committed. Workspace admins can change this setting:
Go to Admin settings > Workspace settings.
Under Repos > Allow Repos to Export IPYNB outputs, select Allow: IPYNB outputs can be toggled on.
When outputs are included, the visualization and dashboard configs are preserved with the .ipynb file format.
When you commit an
.ipynb file, Databricks creates a config file that lets you control how you commit outputs:
If you have a
.ipynbnotebook file but no config file in your repo, open the Git Status modal.
In the notification dialog, click Create commit_outputs file.
You can also generate config files from the File menu. The File menu has a control that lets you automatically update the config file to specify the inclusion or exclusion of outputs for a specific notebook.
In the File menu, select Commit notebooks outputs.
In the dialog box, confirm your choice to commit notebook outputs.
You can convert an existing source notebook in a Git folder to an IPYNB notebook through the Databricks UI.
Open a source notebook in your workspace.
Select File from the workspace menu, and then select Change notebook format [source]. If the notebook is already in IPYNB format, [source] will be [ipynb] in the menu element.
In the modal dialog, select “Jupyter notebook format (.ipynb)” and click Change.
You can also:
View diffs as Code diff (code changes in cells) or Raw diff (code changes are presented as JSON syntax, which includes notebook outputs as metadata).
For more information on the kinds of notebooks supported in Databricks, read Export and import Databricks notebooks.