Creating and managing notebooks

You can add a notebook to your project by using one of these methods: creating a notebook file, copying a sample notebook from the Resource hub, adding a notebook from a local file on your computer, or adding a notebook from a URL.  

Required permissions
You must have the Admin or Editor role in the project to create a notebook.

Watch this short video to learn the basics of Jupyter notebooks.

This video provides a visual method to learn the concepts and tasks in this documentation.

  • Video transcript
    Time Transcript
    00:00 This video covers the basics for working with Jupyter notebooks using watsonx.ai Studio (Watson Studio).
    00:07 Start in a project and add to the project a notebook.
    00:12 Just provide a name and a description and a Python runtime environment to use, then create the notebook.
    00:22 Let's first load a file, so you have some data to work with.
    00:28 Just drag and drop a file into the "Files" slide-out panel.
    00:32 After the file is added to the project, it's available to work with in this notebook.
    00:38 Just click "Insert to code" and insert a pandas DataFrame.
    00:43 Before running the notebook, it's a best practice to insert a cell at the top to describe what the notebook does.
    00:51 Change the cell type to Markdown so this cell will not be treated as code, and then add the description.
    00:59 Now, you're ready to run the notebook.
    01:02 The inserted code loads the data set into a DataFrame, using your credentials for your Cloud Object Storage instance, and then displays the first five rows of the data set.
    01:13 Before returning to the project, save the notebook.
    01:20 On the "Assets" tab, you'll find the notebook.
    01:24 If you open the notebook, it will be in read-only mode.
    01:28 But you can edit the notebook and make changes.
    01:34 For example, you can access the "Information" panel and change the name of the notebook.
    01:41 And on the "Environment" tab, you can change the environment used to run the notebook, as well as stop or restart the runtime environment.
    01:53 If you'd like to share a read-only version of the notebook, you can do that from here.
    01:58 You can select how much of the content you'd like to share and how you want to share the notebook: either through a link or social media.
    02:08 If you'd like to schedule the notebook to run at a different time, you can create a job.
    02:14 Just provide a name for the job and select the notebook version and runtime.
    02:24 Then, select the scheduling options, like: specifying a date for the job to run and whether you'd like the job run to repeat.
    02:43 After you create and run the job, you'll see the status and the job will display on the "Jobs" tab in the project.
    02:55 Find more videos in the Cloud Pak for Data as a Service documentation.

Creating a notebook file in the notebook editor

To create a notebook file in the notebook editor:

  1. From your project, go to the Assets page, click New asset > Work with data and models in Python or R notebooks.

  2. On the New Notebook page, specify the method to use to create your notebook. You can create a blank notebook, choose a sample notebook from the Resource hub, upload a notebook file from your file system, or upload a notebook file from a URL:

    • The notebook file that you select to upload must follow these requirements:
      • The file type must be .ipynb.
      • The file name must not exceed 255 characters.
      • The file name must not contain these characters: < > : ” / | ( ) ?
    • The URL must be a public URL that is shareable and doesn't require authentication.
    • You can find sample notebooks under Samples and in the Resource hub.
  3. Specify the runtime environment for the language that you want to use (Python or R). You can select a provided environment template or an environment template which you created and configured. For more information on environments, see Notebook environments.

  4. Click Create. The notebook opens in edit mode.

    The time that it takes to create a new notebook or to open an existing notebook for editing might vary. If no runtime container is available, a container must be created and only after it is available, the Jupyter notebook user interface can be loaded. The time it takes to create a container depends on the cluster load and size. When a runtime container exists, subsequent calls to open notebooks are significantly faster.

    The opened notebook is locked by you. For more information, see Locking and unlocking notebooks.

  5. Tell the service to trust your notebook content and execute all cells.

    When a new notebook is opened in edit mode, the notebook is considered to be untrusted by the Jupyter service by default. When you run an untrusted notebook, content deemed untrusted will not be executed. Untrusted content includes any Javascript, HTML or Javascript in Markdown cells or in any output cells that you did not generate.

    1. Click Not Trusted in the upper right corner of the notebook.
    2. Click Trust to execute all cells.

Locking and unlocking notebooks

If you open a notebook in edit mode, this notebook is locked by you. While you hold the lock, only you can make changes to the notebook. All other projects users will see the lock icon on the notebook. Only project administrators are able to unlock a locked notebook and open it in edit mode.

When you close the notebook, the lock is released and another user can select to open the notebook in edit mode. Note that you must close the notebook while the runtime environment is still active. The notebook lock can't be released for you if the runtime was stopped or is in idle state. If the notebook lock is not released for you, you can unlock the notebook from the project's Assets page. Locking the file avoids possible merge conflicts that might be caused by competing changes to the file.

Finding your notebooks

You can find and open notebooks from the Assets page of the project.

You can open a notebook in view or edit mode. When you open a notebook in view mode, you can't change or run the notebook. You can only change or run a notebook when it is opened in edit mode and started in an environment.

You can open a notebook by:

  • Clicking the notebook. This opens the notebook in view mode. To then open the notebook in edit mode, click the pencil icon (Edit icon) on the notebook toolbar. This starts the environment that is associated with the notebook.
  • Expanding the three vertical dots on the right of the notebook entry, and selecting View or Edit.

Viewing information about a notebook

You can view the following information about a notebook by clicking the Notebooks asset type in the Assets page of your project:

  • The name of the notebook
  • The date when the notebook was last modified and the person who made the change
  • The programming language of the notebook
  • Whether the notebook is currently locked

Next step

Learn more

Find videos showing how to run a sample notebook from the Resource hub on the Videos page.

Parent topic: Jupyter Notebook editor