Start Building for Free

Resource class overview

7 months ago2 min read
Server v4.x
Server v3.x
On This Page

Use resource classes to:

  • Specify compute resource size (CPU and RAM) for running a job.

  • Optimize executors based on historical trends with resource class Insights.

  • Configure self-hosted runners for use in your .circleci/config.yml file.

  • Specify an execution environment.


The resource_class configuration option has multiple uses: specifying compute resource size, optimizing executors, configuring self-hosted runners, and specifying an execution evironment.

The most common usage is to specify CPU and RAM requirements for a job by configuring the resource_class key for an executor.

    docker: # use the Docker executor
      - image: cimg/base:2022.09 # specify a Docker image
    resource_class: xlarge # specify a resource class
      - run: echo "Hello World"

Executor resource classes are specified by size, for example, small or medium. Each size corresponds to specific CPU and RAM requirements.

When using CircleCI’s self-hosted runners, use the resource_class key in your project configuration to specify which runner to use for a job. Self-hosted runner resource classes are assigned and configured during the installation process.

    machine: true
    resource_class: <my-namespace>/<my-runner>
      - run: echo "Hello runner"

Another use of the resource_class key is to specify an execution environment. For example, Arm is a resource class option when using the machine executor.

      image: ubuntu-2004:202101-01
    resource_class: arm.medium
      - run: uname -a
      - run: echo "Hello, Arm!"


For config examples showing how to use the resource_class key to specify CPU and RAM size for an execution environment, see the following sections of the configuration reference page:

Default resource class

If a resource_class is not explicitly declared for a job, CircleCI will use a default resource class size. Defaults are subject to change. It is best practice to specify a resource class, rather than relying on a default.

Resource class usage tools

Information about the resource classes used in your jobs can be found in the web app, or by using the API. See the sections below for details.

Find the resource class used for a job

The job details page in the web app shows the resource class used for a job.

Screenshot showing how to view the resource class used for a job in the web app
Figure 1. Resource class identifier in web app

Alternatively, use the "Get job details" endpoint to return information about a job, including the resource class used. For usage steps see the get job details how-to guide.

View resource usage per job

To view the compute resource usage for the duration of a job in the CircleCI web app:

  1. Select Dashboard from the sidebar menu

  2. Use the dropdown menus to select a project, and a branch

  3. Expand your workflow ( )

  4. Select a job by clicking on the job name

  5. Select the Resources tab to view CPU and RAM usage for the duration of the job

You can use these insights to decide whether to make changes to the job’s configured resource class. You can also access resource class Insights.

Resources tab

Resource class Insights

Resource class Insights let you track resource utilization for your jobs. You can inspect and use this information to update your executors based on historical trends and job requirements.

To find resource class Insights:

  1. Select Insights from the web app sidebar.

  2. The dashboard shows Insights at the project level. To find resource class Insights you need to drill down to the job level:

    1. Select a project from the drop down.

    2. Select a workflow from the list.

    3. Select the Jobs tab.

    4. Expand a job to view the resource class Insights.

      Screenshot showing resource class Insights
      Figure 2. Resource class Insights

See also

Suggest an edit to this page

Make a contribution
Learn how to contribute