Start Building for Free

Resource class overview

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


The resource_class configuration option has multiple uses. 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. For a full list of available resource class options, see the configuration reference. The resource class product page provides information on credit usage per resource class, and resource class availability for each plan type.

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:

To get started setting up a self-hosted runner, see the Getting started section of the Self-hosted runners overview.

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

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.