Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

JupyterLab Versioning

The Amazon SageMaker Studio interface is based on JupyterLab, which is a web-based interactive development environment for notebooks, code, and data. Studio now supports using both JupyterLab 1 and JupyterLab 3. The default version of JupyterLab in Studio is JupyterLab 3. If you created your Amazon SageMaker Domain and user profile using the Amazon Web Services Management Console before 08/31/2022 or using the Amazon Command Line Interface before 02/22/23, then your Studio instance defaults to JupyterLab 1. After 08/31/2022, JupyterLab version 1 on Amazon SageMaker Studio only receives security fixes. You can choose the version that you want to run. However, you can run only a single instance of JupyterLab at one time per user profile. You can’t run multiple versions of JupyterLab simultaneously.

After 03/31/23, Studio only supports the creation of JupyterLab 3 applications. After that date, Studio stops supporting JupyterLab 1 application creation. On 04/30/2023, Studio removes all existing applications that run JupyterLab 1. Update your existing JupyterLab1 applications to JupyterLab 3 before 04/30/2023 following the steps in View and update the JupyterLab version of an application from the console.

JupyterLab 3

JupyterLab 3 includes the following features that are not available in previous versions. For more information about these features, see JupyterLab 3.0 is released!.

Important changes to JupyterLab 3

Consider the following when using JupyterLab 3:

Restricting default JupyterLab version using an IAM policy condition key

You can use IAM policy condition keys to restrict the version of JupyterLab that your users can launch.

The following policy shows how to limit the JupyterLab version at the Domain level.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Block users from creating JupyterLab 3 apps at the domain level",
            "Effect": "Deny",
            "Action": [
                "sagemaker:CreateDomain",
                "sagemaker:UpdateDomain"
            ],
            "Resource": "*",
            "Condition": {
                "ForAnyValue:StringLike": {
                    "sagemaker:ImageArns": "*image/jupyter-server-3"
                }
            }
        }
    ]
}

The following policy shows how to limit the JupyterLab version at the user profile level.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Block users from creating JupyterLab 3 apps at the user profile level",
            "Effect": "Deny",
            "Action": [
                "sagemaker:CreateUserProfile",
                "sagemaker:UpdateUserProfile"
            ],
            "Resource": "*",
            "Condition": {
                "ForAnyValue:StringLike": {
                    "sagemaker:ImageArns": "*image/jupyter-server-3"
                }
            }
        }
    ]
}

The following policy shows how to limit the JupyterLab version at the application level. The CreateApp request must include the image ARN for this policy to apply.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Block users from creating JupyterLab 3 apps at the application level",
            "Effect": "Deny",
            "Action": "sagemaker:CreateApp",
            "Resource": "*",
            "Condition": {
                "ForAnyValue:StringLike": {
                    "sagemaker:ImageArns": "*image/jupyter-server-3"
                }
            }
        }
    ]
}

Setting a default JupyterLab version

The following sections show how to set a default JupyterLab version for Studio using either the console or the Amazon CLI. 

From the console

You can select the default JupyterLab version to use on either the Domain or user profile level during resource creation. To set the default JupyterLab version using the console, see Onboard to Amazon SageMaker Domain. 

From the Amazon CLI

You can select the default JupyterLab version to use on either the Domain or user profile level using the Amazon CLI. 

To set the default JupyterLab version using the Amazon CLI, you must include the ARN of the desired default JupyterLab version as part of an Amazon CLI command. This ARN differs based on the version and the Region of the SageMaker Domain. 

The following table lists the ARNs of the available JupyterLab versions for each Region:

Create or update Domain

You can set a default JupyterServer version at the Domain level by invoking CreateDomain or UpdateDomain and passing the UserSettings.JupyterServerAppSettings.DefaultResourceSpec.SageMakerImageArn field.

The following shows how to create a Domain with JupyterLab 3 as the default, using the Amazon CLI:

aws --region <REGION> \
sagemaker create-domain \
--domain-name <NEW_DOMAIN_NAME> \
--auth-mode <AUTHENTICATION_MODE> \
--subnet-ids <SUBNET-IDS> \
--vpc-id <VPC-ID> \
--default-user-settings '{
  "JupyterServerAppSettings": {
    "DefaultResourceSpec": {
      "SageMakerImageArn": "arn:aws:sagemaker:<REGION>:<ACCOUNT_ID>:image/jupyter-server-3",
      "InstanceType": "system"
    }
  }
}'

The following shows how to update a Domain to use JupyterLab 3 as the default, using the Amazon CLI:

aws --region <REGION> \
sagemaker update-domain \
--domain-id <YOUR_DOMAIN_ID> \
--default-user-settings '{
  "JupyterServerAppSettings": {
    "DefaultResourceSpec": {
      "SageMakerImageArn": "arn:aws:sagemaker:<REGION>:<ACCOUNT_ID>:image/jupyter-server-3",
      "InstanceType": "system"
    }
  }
}'

Create or update user profile

You can set a default JupyterServer version at the user profile level by invoking CreateUserProfile or UpdateUserProfile and passing the UserSettings.JupyterServerAppSettings.DefaultResourceSpec.SageMakerImageArn field.

The following shows how to create a user profile with JupyterLab 3 as the default on an existing Domain, using the Amazon CLI:

aws --region <REGION> \
sagemaker create-user-profile \
--domain-id <YOUR_DOMAIN_ID> \
--user-profile-name <NEW_USERPROFILE_NAME> \
--query UserProfileArn --output text \
--user-settings '{
  "JupyterServerAppSettings": {
    "DefaultResourceSpec": {
      "SageMakerImageArn": "arn:aws:sagemaker:<REGION>:<ACCOUNT_ID>:image/jupyter-server-3",
      "InstanceType": "system"
    }
  }
}'

The following shows how to update a user profile to use JupyterLab 3 as the default, using the Amazon CLI:

aws --region <REGION> \
sagemaker update-user-profile \
 --domain-id <YOUR_DOMAIN_ID> \
 --user-profile-name <EXISTING_USERPROFILE_NAME> \
--user-settings '{
  "JupyterServerAppSettings": {
    "DefaultResourceSpec": {
      "SageMakerImageArn": "arn:aws:sagemaker:<REGION>:<ACCOUNT_ID>:image/jupyter-server-3",
      "InstanceType": "system"
    }
  }
}'

View and update the JupyterLab version of an application from the console

The following shows how to view and update the JupyterLab version of an application.

Installing JupyterLab and Jupyter Server extensions

The process for installing JupyterLab and Jupyter Server extensions differs depending on the JupyterLab version of your Studio instance. In JupyterLab 1, you can open the terminal and install extensions without activating any conda environment. In JupyterLab 3, you must activate the studio conda environment before installing extensions. The method for this differs if you're installing the extensions from within Studio or using a lifecycle configuration script.

Installing Extension from within Studio

To install extensions from within Studio, you must activate the studio environment before you install extensions.

# Before installing extensions
conda activate studio

# Install your extensions
pip install <JUPYTER_EXTENSION>

# After installing extensions
conda deactivate

Installing Extensions using a lifecycle configuration script

If you're installing JupyterLab and Jupyter Server extensions in your lifecycle configuration script, you must modify your script so that it works with JupyterLab 3. The following sections show the code needed for existing and new lifecycle configuration scripts.

Existing lifecycle configuration script

If you're reusing an existing lifecycle configuration script that must work with both versions of JupyterLab, use the following code in your script:

# Before installing extension
export AWS_SAGEMAKER_JUPYTERSERVER_IMAGE="${AWS_SAGEMAKER_JUPYTERSERVER_IMAGE:-'jupyter-server'}"
if [ "$AWS_SAGEMAKER_JUPYTERSERVER_IMAGE" = "jupyter-server-3" ] ; then
   eval "$(conda shell.bash hook)"
   conda activate studio
fi;

# Install your extensions
pip install <JUPYTER_EXTENSION>


# After installing extension
if [ "$AWS_SAGEMAKER_JUPYTERSERVER_IMAGE" = "jupyter-server-3" ]; then
   conda deactivate
fi;

New lifecycle configuration script

If you're writing a new lifecycle configuration script that only uses JupyterLab 3, you can use the following code in your script:

# Before installing extension
eval "$(conda shell.bash hook)"
conda activate studio


# Install your extensions
pip install <JUPYTER_EXTENSION>


conda deactivate