You can create and manage notebooks using the UI, the CLI, and by invoking the Workspace API. This topic focuses on performing notebook tasks using the UI. For the other methods, see Databricks CLI and Workspace API.

Notebooks are one interface for interacting with Azure Databricks. If you have enabled the Azure Databricks Premium Plan, you can use Workspace access control to control sharing of notebooks and folders in the Workspace.

Create a notebook

  1. Click the Workspace button Workspace Icon or the Home button Home Icon in the sidebar. Do one of the following:

    • Next to any folder, click the Menu Dropdown on the right side of the text and select Create > Notebook.

      Create Notebook
    • In the Workspace or a user folder, select Down Caret Create > Notebook.

  2. In the Create Notebook dialog, enter a name and select the notebook’s primary language. Notebooks support Python, Scala, SQL, and R as their primary language.

  3. Click Create.

Notebook external formats

Azure Databricks supports several notebook external formats:

A source file with an extension .scala, .py, .sql, or .r.
An Azure Databricks proprietary notebook format with an .html extension.
A Databricks archive.
IPython Notebook
An exported Jupyter notebook with the extension .ipynb.
An R Markdown document with the extension .Rmd.

Import a notebook

You can import an external notebook from a URL or a file.

  1. Click the Workspace button Workspace Icon or the Home button Home Icon in the sidebar. Do one of the following:

    • Next to any folder, click the Menu Dropdown on the right side of the text and select Import.

    • In the Workspace or a user folder select Down Caret Import.

  2. Specify the URL to or browse a file containing a supported external format.

  3. Click Import.

Export a notebook

Select File > Export and a format.


When you export a notebook as a Databricks notebook (HTML), IPython notebook, or archive (DBC), and you have not previously cleared the results, the results of running the notebook are included.

Attach a notebook to a cluster

Before you can do any work in a notebook, you must first attach the notebook to a cluster. In the notebook toolbar, click Detached under the notebook’s name at the top left. From the dropdown, select a running cluster.

Use a notebook

Keyboard shortcuts

Keyboard shortcuts shortcuts make it much easier to use notebooks and execute code. Toggle the shortcut display by clicking the shortcuts link under a cell, the Keyboard Icon icon at the top, or at the top right under the ?.


Add a cell

To add a cell (add a command), mouse over a cell at the top or bottom and click the Add Cell icon, or access the notebook cell menu at the far right by and click Down Caret > Add Cell Above or Down Caret > Add Cell Below.

Delete a cell

To delete a cell (delete a command), go to the cell actions Cell Actions at the far right of the cell and click Delete Cell (Delete).

Predefined variables

Notebooks have some Apache Spark variables already defined.

Class Variable Name
SparkContext sc
SQLContext/HiveContext sqlContext
SparkSession (Spark 2.x) spark


Do not create a SparkSession, SparkContext, or SQLContext. Doing so will lead to inconsistent behavior.

Determine Spark and Databricks Runtime versions

To determine the Spark version of the cluster your notebook is attached to, run:


To determine the Databricks Runtime version of the cluster your notebook is attached to, run:

  • Scala

  • Python



Both this sparkVersion tag and the spark_version property required by the endpoints in the Clusters API and Jobs API refer to the Databricks Runtime version, not the Spark version.

Run a cell

To run code, type the code in a cell and either select Run Icon > Run Cell or press shift+Enter. For example, try executing these Python code snippets.


Now that you’ve seen the pre-defined variables, run some real code!

1+1 # => 2

Run all cells

To run all the cells in a notebook, select Run All in the notebook toolbar.


Do not do a Run All if steps for mount and unmount are in the same notebook. It could lead to a race condition and possibly corrupt the mount points.

Clear notebooks state and results

To clear the notebook state and results, select Clear > <action> in the notebook menubar:


Hide and show cell content

Cell content consists of cell code and the result of running the cell. You can hide and show the cell code and result using the cell actions Cell Actions at the top right.

To hide cell code:

  • Select Down Caret > Hide Code

To hide and show the cell result:

  • Select Down Caret > Hide Result
  • Select Cell Minimize
  • Type Esc > Shift + o

To show hidden cell code or result, click the Show links:


Mix languages

While a notebook has a primary language, you can mix languages by specifying the language magic command %<language> at the beginning of a cell. %<language> allows you to execute <language> code even if that notebook’s primary language is not <language>. The supported magic commands are: %python, %r, %scala, and %sql. Additionally:

Allows you to execute shell code in your notebook. Add the -e option in order to fail this cell (and subsequently a job or a run all command) if the shell command does not success. By default, %sh alone will not fail a job even if the %sh command does not completely succeed. Only %sh -e will fail if the shell command has a non-zero exit status.
Allows you to use Databricks Utilities filesystem commands. Read more on the Databricks File System - DBFS pages.

Include documentation

To include documentation in a notebook you can use the %md magic command to identify Markdown markup. The included Markdown markup is rendered into HTML. For example, this Markdown snippet:

%md # Hello This is a Title

is rendered as a HTML title:


Display mathematical equations

Notebooks support KaTeX for displaying mathematical formulas and equations. For example,


\\(c = \\pm\\sqrt{a^2 + b^2} \\)


$$c = \\pm\\sqrt{a^2 + b^2}$$


renders as:




\\( f(\beta)= -Y_t^T X_t \beta + \sum log( 1+{e}^{X_t\bullet\beta}) + \frac{1}{2}\delta^t S_t^{-1}\delta\\)

where \\(\delta=(\beta - \mu_{t-1})\\)

renders as:


Include HTML

You can include HTML in a notebook by using the function displayHTML. See HTML, D3, and SVG in Notebooks for an example of how to do this.

Command comments

You can have discussions with collaborators using command comments.

To toggle the Comments sidebar, click the Comments button at the top right of a notebook.


To add a comment to a command:

  1. Highlight command text and click the comment bubble:

  2. Add your comment and click Comment.


To edit, delete, or reply to a comment, click the comment, and choose an action.


Show line and command numbers

To show line numbers or command numbers, click View > Show line numbers or View > show command numbers. Once they’re displayed, you can hide them again from the same menu. You can also enable line numbers with the keyboard shortcut Control+L.

Show line or command numbers via the view menu
Line and command numbers enabled in notebook

If you enable line or command numbers, Databricks saves your preference and will show them in all of your other notebooks for that browser.

Command numbers above cells link to that specific command. If you click on the command number for a cell, it updates your URL to be anchored to that command. If you want to link to a specific command in your notebook, right-click the command number and choose copy link address.

Python and Scala error highlighting

Python and Scala notebooks support error highlighting. That is, the line of code that is throwing the error will be highlighted in the cell. Additionally, if the error output is a stacktrace, the cell in which the error is thrown is displayed in the stacktrace as a link to the cell. You can click this link to jump to the offending code.

../../_images/notebook-python-error-highlighting.png ../../_images/notebook-scala-error-highlighting.png

Find and replace text

To find and replace text within a notebook, select File > Find and Replace.


The current match is highlighted in orange and all other matches are highlighted in yellow.


You can replace matches on an individual basis by clicking Replace.

You can switch between matches by clicking the Prev and Next buttons or pressing shift+enter and enter to go to the previous and next matches, respectively.

Close the find and replace tool by clicking the x button or pressing esc.

Download result

Once you’ve run a cell, you may want to download the result to your local machine. To do so, click the Download Result button at the bottom of a cell that contains tabular output. You’ll see an option to download a preview of the result or the full result.

You can try this out by running

%sql SELECT 1

and downloading the result.

Run a notebook from another notebook

You can run a notebook from another notebook by using the %run magic command. This is roughly equivalent to a :load command in a Scala REPL on your local machine or an import statement in Python. All variables defined in that other notebook become available in your current notebook.

For example, suppose you have notebookA and notebookB. notebookA contains a cell that has the following Python code:

x = 5

Running this code snippet in notebookB works even though x was never explicitly created.

%run /Users/path/to/notebookA

print(x) # => 5

To specify a relative path, preface it with ./ or ../. For example, if notebookA and notebookB are in the same directory you can alternatively run them from a relative path.

%run ./notebookA

print(x) # => 5
%run ../someDirectory/notebookA # up a directory and into another

print(x) # => 5


%run must be in a cell by itself as it runs the entire notebook inline.


Notifications alert you to certain events, such as which command is currently running during Run all cells and which commands are in error state. When your notebook is showing multiple error notifications, the first one will have a link that allows you to clear all notifications.

Notebook notifications are enabled by default. You can disable them under User Settings > Notebook Settings.

Notebook isolation

Databricks supports two types of isolation: variable and class and Spark session.


Since all notebooks attached to the same cluster execute on the same cluster VMs, even with Spark session isolation enabled there is no guaranteed user isolation within a cluster.

Variable and class isolation

Variables and classes are available only in the current notebook. For example, two notebooks attached to the same cluster can define variables and classes with the same name but these objects are distinct.

To define a class that is visible to all notebooks attached to the same cluster, define the class in a package cell. Then, you can access the class by using its fully qualified name, which is the same as accessing a class in an attached Scala or Java library.

Spark session isolation

For a cluster running Apache Spark 2.0.0 and above, every notebook has a pre-defined variable called spark representing a SparkSession. A SparkSession is the entry point for using different APIs in Spark as well as setting different runtime configurations.

For Spark 2.0.0 and Spark 2.0.1-db1, notebooks attached to a cluster share the same SparkSession. From Spark 2.0.2-db1, you can enable Spark session isolation so that every notebook uses its own SparkSession. When Spark session isolation is enabled:

  • Runtime configurations set using spark.conf.set or using SQL’s set command affect only the current notebook. Configurations for a metastore connection are not runtime configurations and all notebooks attached to a cluster share these configurations.
  • Setting the current database affects only the current notebook.
  • Temporary views created by dataset.createTempView, dataset.createOrReplaceTempView, and SQL’s CREATE TEMPORARY VIEW command are visible only in the current notebook.

To enable Spark session isolation, set spark.databricks.session.share to false in the Spark Config field.

In Spark 2.0.2 session isolation is disabled. In Spark 2.1 and above session isolation is enabled. In addition, from Spark 2.1, you can use global temporary views to share temporary views across notebooks. See Create View.

Cells that trigger commands in other languages (that is, cells using %scala, %python, %r, and %sql) and cells that include other notebooks (that is, cells using %run) are part of the current notebook. Thus, these cells are in the same session as other notebook cells. In contrast, Notebook Workflows run a notebook with an isolated SparkSession, which means temporary views defined in such a notebook are not visible in other notebooks.


Databricks supports two types of autocomplete in your notebook: local and server.

Local autocomplete completes words that exist in the notebook. Server autocomplete is more powerful because it accesses the cluster for defined types, classes, and objects and SQL database and table names. To activate server autocomplete you must attach your notebook to a running cluster and run all cells that define completable objects.


  • Server autocomplete in Scala, Python, and R notebooks is blocked during command execution.
  • Server autocomplete is not available for high concurrency clusters.

You trigger autocomplete by pressing Tab after entering a completable object. For example, after you define and run the cells containing the definitions of MyClass and instance, the methods of instance are completable and list of valid completions displays when you press Tab.


Type completion and SQL database and table name completion work in the same way.

Type Completion — — SQL Completion

Schedule a notebook

To schedule a notebook job to run periodically:

  1. Click the Schedule button at the top right.
  2. Click + New.
  3. Choose the schedule.
  4. Click OK.

Delete a notebook

Since notebooks are contained inside the Workspace (and in folders in the Workspace), they follow the same rules as folders. See Folder actions for information about how to access the Workspace menu and delete notebooks or other items in the Workspace.

Databricks archives

A Databricks archive is a package that lets you distribute collections of Azure Databricks HTML notebooks. A Databricks archive is a JAR file with extra metadata and has the extension .dbc.

Export an archive

Select the Down Caret or Menu Dropdown to the right of a folder or notebook and select Export > DBC Archive. Azure Databricks downloads a file named <[folder|notebook]-name>.dbc.

Import an archive

  1. Select the Down Caret or Menu Dropdown to the right of a folder or notebook and select Import.
  2. Choose File or URL.
  3. Go to or drop a Azure Databricks archive in the dropzone.
  4. Click Import. The archive is imported into Azure Databricks. If the archive contains an exported folder, Azure Databricks recreates that folder.

Extract an archive

To extract the notebooks from an archive, run:

jar xvf <archive>.dbc

Version control

Azure Databricks has basic version control for notebooks. To access version control, click the Revision History menu on the top right of every notebook.

To add a comment to the latest revision:

  1. Click the revision.

  2. Click the Save now link.

  3. In the Save Notebook Revision dialog, enter a comment.

  4. Click Save. The notebook revision is saved with the entered comment.

To restore an earlier revision:

  1. Click the revision.

  2. Click Restore this revision.

  3. Click Confirm. The selected revision becomes the latest revision of the notebook.

To delete a notebook’s revision entry:

  1. Click the revision.

  2. Click the trash icon Trash Icon.

  3. Click Yes, erase. The selected revision is deleted from the notebooks’ revision history.

To clear a notebook’s revision history:

  1. Select File > Clear Revision History.

  2. Click Yes, clear. The notebook revision history is cleared.


    Once cleared, the revision history is not recoverable.

Databricks also integrates with these third-party version control tools: