Run notebook executions with parameters

Vertex AI Workbench managed notebooks isdeprecated. On April 14, 2025, support for managed notebooks ended and the ability to create managed notebooks instances was removed. Existing instances will continue to function until March 30, 2026, but patches, updates, and upgrades won't be available. To continue using Vertex AI Workbench, we recommend that youmigrate your managed notebooks instances to Vertex AI Workbench instances.

Vertex AI Workbench managed notebooks instanceslet you use parameter values in your notebook executionsto specify differences in how your notebook file's code runs.This page describes how to set up your notebook file to use parametersand how to run executions that specify different valuesfor your notebook parameters.

Use parameters to run different iterations of your notebook file

You can use notebook parameter values in your executionsto run the same notebook code while specifying differences like the following:

• Specify a different dataset to use, or a different sample sizeof the dataset.

• Specify different model configurations such as learning rate oroptimizer type.

• Run different models, or run different versions of the same model.

How to use parameters in a notebook execution

The process for executing a notebook with parameters has two main steps:

1. Add theparameters tag to one of your notebook file's cells.While this isn't a technical requirement, this celltypically contains code that assigns values to your parametervariables, though this is not a technical requirement.If you don't assign different parameter values in your execution,the execution uses the parameter values in your notebook fileas default values.

2. Create an execution for your notebook file that includesnew values for your parameters. Use thefollowing pattern to format your parameters and their values:parameter1=value1,parameter2=value2. The format requires commasbetween parameter-value pairs, no spaces, and no quotation marks.When your execution runs,the executor adds a cell to the notebook that updates thevalues of your parameters directly following the cell thatis taggedparameters.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Notebooks and Vertex AI APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Notebooks and Vertex AI APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the APIs

Required roles

To ensure that your instance's service account has the necessary permissions to interact with the Vertex AI Workbench executor, ask your administrator to grant your instance's service account the following IAM roles on the project:

• Notebooks Viewer (roles/notebooks.viewer)
• Vertex AI User (roles/aiplatform.user)
• Storage Admin (roles/storage.admin)

For more information about granting roles, seeManage access to projects, folders, and organizations.

Your administrator might also be able to give your instance's service account the required permissions throughcustom roles or otherpredefined roles.

Open JupyterLab

To open JupyterLab and prepare a notebook file to run,complete the following steps.

1. Open JupyterLab.

2. Upload a notebook (ipynb) file, open an existing file,oropen a new notebookfileand add the code that you want to run to the new notebook.

3. Make sure your notebook file's code meets therequirementsfor using the executor.

Add theparameters tag to a notebook cell

1. In your managed notebooks instance'sJupyterLab user interface, open the notebook file that you want to run.

2. Write code in one cell that assigns values toyour parameter variables.These are the values your notebook file uses ifyou don't assign different parameter values in your execution.

3. Make sure your parameters cell is still selected, and thenin the right sidebar, click the Property inspector.

4. In the property inspector, in theCell Tags section,clickAdd Tag, enterparameters, and then pressEnter.

   Note: If you tag more than one cell withparameters, the executoradds only one parameters cell directly following the first cellwith theparameters tag.

Provide parameter values for your execution

1. In your managed notebooks instance'sJupyterLab user interface, click the Executor button.

2. In theSubmit notebooks to Executor dialog,enter a name for your execution in theExecution name field.

3. Select aMachine type andAccelerator type.

4. Select anEnvironment.

5. In theType field,selectOne-time execution, orselectSchedule-based recurring executions, and completethe dialog for scheduling executions.

6. InAdvanced options,select theRegion where you want to run your notebook.

7. In theCloud Storage bucket field,select an available Cloud Storage bucket orenter a name for a new bucket and clickCreate and select.The executor stores your notebook outputin this Cloud Storage bucket.

8. In theNotebook parameterization sectionand theInput parameters text box,add notebook parameters separated by commas, for exampleoptimizer=SGD,learning_rate=0.01. The format requiresthat there are no spaces and no quotation marks.

9. Configure the rest of your execution, and then clickSubmit.

What's next

• Learn more abouthow to run notebook code inthe executor.