Manage your environment - Amazon SageMaker

Manage your environment

Amazon SageMaker Studio Lab provides 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 activating an environment, installing packages in the environment, and then selecting the environment as a Kernel. For more information on activating the environment, see Create, activate, and use new conda environments.

Your Studio Lab environment comes with a base image installed that includes key packages and resources. You can customize your environment by adding new packages and libraries to it. You can also create new environments from Studio Lab, import compatible environments, reset your environment to create space, and more.

The commands on this page will be for running in a Studio Lab terminal. If you wish to run these commands in a Studio Lab 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.

Base image

The default Amazon SageMaker Studio Lab base image includes the following packages.

  • Python 3.9

  • bzip2

  • build-essential

  • curl

  • git

  • libgl1-mesa-glx

  • nano

  • rsync

  • unzip

  • wget

  • ca-certificates

  • pip

  • ipykernel-6.4

Supported ML frameworks and libraries

Machine learning frameworks simplify machine learning by abstracting complex algorithms and processes. This abstraction helps you get started with machine learning. Libraries are collections of files, programs, and other resources that you can use in your code. Studio Lab supports the following frameworks and libraries, which you must install manually.

  • PyTorch 1.9

  • TensorFlow 1.15 and 2.6

  • MxNet 1.8

  • Hugging Face

  • AutoGluon 0.3.1

  • Scikit-learn 0.24

  • PyTorch ecosystem

  • OpenCV

  • scipy

  • numpy

For a list of all of the packages currently installed in your environment, run the following command from your Jupyter notebook.

pip list

Managing conda environments

The following sections give information about your default conda environment, how to customize it, and how to add and remove conda environments. For more information about conda environments, see 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.

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

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.


Maintaining multiple environments counts against your available Studio Lab memory.

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.

  1. Clone the SageMaker Studio Lab Examples GitHub repository by following the instructions in Use GitHub resources.

  2. In Studio Lab choose the File Browser icon ( ) on the left menu, so that the File Browser panel shows on the left.

  3. Navigate to the studio-lab-examples/custom-environments directory in the File Browser.

  4. Open the directory for the environment that you want to build.

  5. Right click the .yml file in the folder, then select Build conda Environment.

  6. You can now use the environment as a kernel after your conda environment has finished building. For instructions on how to use an existing environment as a kernel, see Create, activate, and use new conda environments

Customize your environment

You can customize your environment by installing and removing extensions and packages, as needed. Any installed extensions and packages persist in your project, so you do not need to install your packages every time you work on your project.


Installed packages counts against your available Studio Lab memory

To view your environments, see View environments.

To activate your environment, see Create, activate, and use new conda environments.

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

Install packages

To install additional packages to your environment from a Jupyter notebook, run one of the following commands in a Studio Lab terminal. These commands install packages in the currently activated environment. Any packages that you install are saved in your persistent project directory. 

  • conda install <PACKAGE>

  • pip install <PACKAGE>

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, 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.

  1. List all conda environments.

    conda env list
  2. Activate the base environment.

    conda activate base
  3. Remove each environment in the list of conda environments, besides base.

    conda remove --name <ENVIRONMENT_NAME> --all
  4. Delete all of the files on your Studio Lab.

    rm -rf *.*