JupyterLab Versioning

The Amazon SageMaker Studio Classic interface is based on JupyterLab, which is a web-based interactive development environment for notebooks, code, and data. Studio Classic only supports using JupyterLab 3.

If you created your domain and user profile using the AWS Management Console before 08/31/2022 or using the AWS Command Line Interface before 02/22/23, then your Studio Classic instance defaulted to JupyterLab 1. After 07/01/2024, you cannot create any Studio Classic applications that run JupyterLab 1.

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 Classic using either the console or the AWS 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 Amazon SageMaker AI domain overview. 

From the AWS CLI

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

To set the default JupyterLab version using the AWS CLI, you must include the ARN of the desired default JupyterLab version as part of an AWS CLI command. This ARN differs based on the version and the Region of the SageMaker AI 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 AWS 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 AWS 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 AWS 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 AWS 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

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 Classic or using a lifecycle configuration script.

Installing Extension from within Studio Classic

To install extensions from within Studio Classic, 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