Skip to main content
Version: Latest

Container images

Check your docs version

These docs are for the new Anyscale design. If you started using Anyscale before April 2024, use Version 1.0.0 of the docs. If you're transitioning to Anyscale Preview, see the guide for how to migrate.

Container images are the standard for production workloads. These isolated environments encapsulate all necessary elements for software execution, including code, runtime, system tools, libraries, and settings, ensuring consistent operation across different computing environments. Anyscale integrates container images as a core concept; all clusters (Workspaces, Jobs, or Services) run with a predefined container image. Simply pass the URI of any image using --image-uri to use it in your application.

Base Images

Anyscale provides a set of pre-built container images out of the box with permutations of Ray versions, Python, and other common dependencies.


You can distinguish the image type by the naming convention.

For example: anyscale/ray:2.30.0-slim-py310-cu123 means:

  • Ray version is 2.30.0.
  • Image type is slim.
  • Python version is 3.10.
  • CUDA version is 12.3.

Anyscale base images come in multiple flavors:

  1. Slim images: These images contain the minimum set of dependencies required to run on Anyscale. We recommend starting with slim images for the best performance, for example, anyscale/ray:2.30.0-slim-py310.
  1. Ray images: These are the official rayproject/ray images, for example, anyscale/ray:2.30.0.

  2. Ray ML CPU images: These are the CPU flavor of the rayproject/ray-ml pipeline, for example, anyscale/ray-ml:2.30.0-py310-cpu.

  3. Ray ML GPU images: These are the GPU flavor of the rayproject/ray-ml pipeline, for example, anyscale/ray-ml:2.30.0-py310-gpu.

Customizing a container image

Anyscale offers a cloud-hosted image build-farm that provides a simple and powerful way to quickly iterate over the Anyscale base images. On every iteration, Anyscale generates a new revision number, making it easy to revert to previous versions if needed.

To build a custom container image, you can use a Dockerfile-like interface where you specify the base Anyscale image. This interface supports the following Dockerfile instructions:

  • FROM: Create a new build from an Anyscale base image. Currently, only Anyscale base images are supported. Reach out to if you would like to use other images in the build farm.
  • ENV: Set environment variables.
  • WORKDIR: Change the working directory. Note, this is only for build time and does not affect where Anyscale starts your job, service, or the workspace default working directory.
  • COPY: Copy files and directories only from a previous build stage, not from local storage.
  • RUN: Execute build commands.

You can create a container image from the UI, CLI, or SDK.

  1. Go to container images.
  1. Click on the Create button.

Create container image

  1. Define the name of the image. Note how the URI of the image is generated. This URI is how you reference this image in the future when creating your Anyscale workspace, jobs, or services.
  2. Define the content of the image.

Container image source

Start a cluster with a container image

You can use the image-uri generated above to start any cluster on Anyscale.

For new workspaces:

  1. Go to the workspaces page.
  2. Click on the Create button, then "Custom blank workspace".

create blank workspace

  1. In the "Container image" section, select use my own image and configure the image_uri and the ray version. create blank workspace container configuration

For existing workspaces:

  1. Go to the dependency tab
  2. Click the edit button on the container image.
  3. Select "Use my own image" option.


Bring your own image

Anyscale supports externally built images. Simply pass in the URI of your image in the image_uri field as you would for Anyscale-hosted images. However, ensure that your image adheres to Anyscale's minimum requirements.

For customer-hosted clouds, these images need to be accessible by your cloud (for example, an ECR registry in AWS). For Anyscale-hosted clouds, the images must be in a public registry (for example, Docker Hub).

You can review our complete guide on how to build your own custom image for more information.

  1. Go to the dependency tab.
  2. Click the edit button on the container image.
  3. Select the "Use my own image" option.

workspace 4. Make sure to choose the version of Ray you have installed in your image.