Manage your environment

Amazon SageMaker Studio Lab provides pre-installed environments for your Studio Lab notebook instances. Environments allow you to start up a Studio Lab notebook instance with the packages you want to use. This is done by installing packages in the environment and then selecting the environment as a Kernel.

Studio Lab has various environments pre-installed for you. You will typically want to use the sagemaker-distribution environment if you want to use a fully managed environment that already contains many popular packages used for machine learning (ML) engineers and data scientists. Otherwise you can use the default environment if you want persistent customization for your environment. For more information on the available pre-installed Studio Lab environments, see Studio Lab pre-installed environments.

You can customize your environment by adding new packages (or libraries) to it. You can also create new environments from Studio Lab, import compatible environments, reset your environment to create space, and more.

The following commands are for running in a Studio Lab terminal. However, while installing packages it is highly recommended to install them within your Studio Lab Jupyter notebook. This ensures that the packages are installed in the intended environment. To run the commands in a Jupyter notebook, prefix the command with a % before running the cell. For example, the code snippet pip list in a terminal is the same as %pip list in a Jupyter notebook.

The following sections give information about your default conda environment, how to customize it, and how to add and remove conda environments. For a list of sample environments that you can install into Studio Lab, see Creating Custom conda Environments. To use these sample environment YAML files with Studio Lab, see Step 4: Install your Studio Lab conda environments in Studio Classic.

Your default environment

Studio Lab uses conda environments to encapsulate the software packages that are needed to run notebooks. Your project contains a default conda environment, named default, with the IPython kernel. This environment serves as the default kernel for your Jupyter notebooks.

View environments

To view the environments in Studio Lab you can use a terminal or Jupyter notebook. The following command will be for a Studio Lab terminal. If you wish to run the corresponding commands in a Jupyter notebook, see Manage your environment.

Open the Studio Lab terminal by opening the File Browser panel ( ), choose the plus (+) sign on the menu at the top of the file browser to open the Launcher, then choose Terminal. From the Studio Lab terminal, list the conda environments by running the following.

conda env list

This command outputs a list of the conda environments and their locations in the file system. When you onboard to Studio Lab, you automatically activate the studiolab  conda environment. The following is an example of listed environments after you onboard.

# conda environments:
#
default                  /home/studio-lab-user/.conda/envs/default
studiolab             *  /home/studio-lab-user/.conda/envs/studiolab
studiolab-safemode       /opt/amazon/sagemaker/safemode-home/.conda/envs/studiolab-safemode
base                     /opt/conda
sagemaker-distribution     /opt/conda/envs/sagemaker-distribution

The * marks the activated environment.

Create, activate, and use new conda environments

If you would like to maintain multiple environments for different use cases, you can create new conda environments in your project. The following sections show how to create and activate new conda environments. For a Jupyter notebook that shows how to create a custom environment, see Setting up a Custom Environment in SageMaker Studio Lab.

Create conda environment

To create a conda environment, run the following conda command from your terminal. This example creates a new environment with Python 3.9.

conda create --name <ENVIRONMENT_NAME> python=3.9

Once the conda environment is created, you can view the environment in your environment list. For more information on how to view your environment list, see View environments.

Activate a conda environment

To activate any conda environment, run the following command in the terminal.

conda activate <ENVIRONMENT_NAME>

When you run this command, any packages installed using conda or pip are installed in the environment. For more information on installing packages, see Customize your environment.

Use a conda environment

To use your new conda environments with notebooks, make sure the ipykernel package is installed in the environment.

conda install ipykernel

Once the ipykernel package is installed in the environment, you can select the environment as the kernel for your notebook.

You may need to restart JupyterLab to see the environment available as a kernel. This can be done by choosing Amazon SageMaker Studio Lab in the top menu of Studio Lab and choosing Restart JupyterLab....

When you create a new notebook from the Studio Lab Launcher, you will have the option to choose the kernel under Notebook. For an overview of the Studio Lab UI, see Amazon SageMaker Studio Lab UI overview.

When a Jupyter notebook is open, you can choose the kernel by choosing Kernel from the top menu and choose Change Kernel....

Using sample Studio Lab environments

Studio Lab provides sample custom environments through the SageMaker Studio Lab Examples repository. The following shows how to clone and build these environments.

Customize your environment

You can customize your environment by installing and removing extensions and packages as needed. Studio Lab comes with environments with packages pre-installed and using an existing environment may save you time and memory, as pre-installed packages do not count against your available Studio Lab memory. For more information on the available pre-installed Studio Lab environments, see Studio Lab pre-installed environments.

Any installed extensions and packages installed on your default environment will persist in your project. That is, you do not need to install your packages for every project runtime session. However, extensions and packages installed on your sagemaker-distribution environment will not persist, so you will need to install new packages during your next session. Thus, it is highly recommended to install packages within your notebook to ensure that the packages are installed in the intended environment.

To view your environments, run the command conda env list.

To activate your environment, run the command conda activate <ENVIRONMENT_NAME>.

To view the packages in an environment, run the command conda list.

Install packages

It is highly recommended to install your packages within your Jupyter notebook to ensure that your packages are installed in the intended environment. To install additional packages to your environment from a Jupyter notebook, run one of the following commands in a cell within your Jupyter notebook. These commands install packages in the currently activated environment.

We don't recommend using the !pip or !conda commands because they can behave in unexpected ways when you have multiple environments.

After you install new packages to your environment, you may need to restart the kernel to ensure that the packages work in your notebook. This can be done by choosing Amazon SageMaker Studio Lab in the top menu of Studio Lab and choosing Restart JupyterLab....

Remove packages

To remove a package, run the command

%conda remove <PACKAGE_NAME>

This command will also remove any package that depends on <PACKAGE_NAME>, unless a replacement can be found without that dependency.

To remove all of the packages in an environment, run the command

conda deactivate
&& conda env remove --name
<ENVIRONMENT_NAME>

Refresh Studio Lab

To refresh Studio Lab, remove all of your environments and files.