--- title: "Optimization reference" description: "Ways to optimize your CircleCI pipelines, from reducing data usage with storage controls and workspaces to cutting build time with caching and parallelism." platform: "Cloud, Server" doc_version: "Server" last_updated: "2026-10-15" --- > For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md). > > For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt). # Optimization reference This page provides an overview of the various ways you can optimize your CircleCI configuration. Each optimization method is described briefly, along with possible use cases. ## Optimize your data usage ### Workspaces Workspaces are used to pass along data that is _unique to a run_ and is needed for _downstream jobs_. A job that runs early in your workflow might fetch data and then make it _available later_ for jobs that run later in that workflow. To persist data from a job and make it available to downstream jobs via the [`attach_workspace`](https://circleci.com/docs/reference/configuration-reference/#attachworkspace) key, configure the job to use the [`persist_to_workspace`](https://circleci.com/docs/reference/configuration-reference/#persisttoworkspace) key. Files and directories named in the `paths:` property of `persist_to_workspace` will be uploaded to the workflow’s temporary workspace relative to the directory specified with the root key. The files and directories are then uploaded and made available for subsequent jobs (and re-runs of the workflow) to use. * Read more on the [Workspaces](https://circleci.com/docs/guides/server/orchestrate/workspaces/) page. ## Reduce build time ### Docker image choice Choosing the right Docker image for your project can have a huge impact on build time. For example, a basic language image requires downloading dependencies and tools on every pipeline run. An image with those dependencies pre-installed saves that time on every build run. When configuring your projects and specifying images, consider the following options: * CircleCI provides a range of [Convenience Images](https://circleci.com/docs/guides/server/execute/circleci-images/), typically based on official Docker images, but with a range of useful language tools pre-installed. * You can create [Custom Images](https://circleci.com/docs/guides/server/execute/custom-images/), maximizing specificity for your projects. To help with this, we provide [Guidance for Building Images Manually](https://circleci.com/docs/guides/server/execute/custom-images/#creating-a-custom-image-manually). ### Docker layer caching Docker layer caching is a feature that can help to reduce the _build time_ of a Docker image in your build. DLC is useful if you find yourself frequently building Docker images as a regular part of your CI/CD process. DLC is similar to _caching dependencies_ in that it _saves_ the image layers that you build within your job, making them available on subsequent builds. * Read more on the [Docker Layer Caching](https://circleci.com/docs/guides/server/optimize/docker-layer-caching/) page. ### Caching dependencies Caching is one of the first optimizations to consider for your jobs. If a job fetches data at any point, it is likely that you can make use of caching. A common example is the use of a package/dependency manager. If your project uses Yarn, Bundler, or Pip, for example, the dependencies downloaded during a job can be cached for later use rather than being re-downloaded on every build. * Read more on the [Caching Dependencies](https://circleci.com/docs/guides/server/optimize/caching/) page. ### Workflows Workflows provide a means to define a collection of jobs and their run order. If at any point in your configuration you see a step where two jobs could happily run independently of one another, workflows may be helpful. Workflows also provide several other features to augment and improve your CI/CD configuration. Read more about workflows on the [Workflow](https://circleci.com/docs/guides/server/orchestrate/workflows/) page. * You can view examples of workflows in the [CircleCI demo workflows repository](https://github.com/CircleCI-Public/circleci-demo-workflows/). ### Parallelism If your project has a large test suite, configure your build to use [`parallelism`](https://circleci.com/docs/reference/configuration-reference/#parallelism) with [CircleCI’s test splitting functionality](https://circleci.com/docs/guides/server/optimize/parallelism-faster-jobs/) or a [third party application or library](https://circleci.com/docs/guides/server/optimize/parallelism-faster-jobs/#other-ways-to-split-tests). This splits your tests across multiple machines. CircleCI supports automatic test allocation across machines/containers on a file basis. You can also manually customize how tests are allocated. * Read more about splitting tests across parallel execution environments on the [Parallelism and Test Splitting](https://circleci.com/docs/guides/server/optimize/parallelism-faster-jobs/) page. * Refer to the [Use the CircleCI CLI to Split Tests](https://circleci.com/docs/guides/server/optimize/use-the-circleci-cli-to-split-tests/) how-to guide. * Follow the [Parallelism and Test Splitting](https://circleci.com/docs/guides/server/optimize/parallelism-faster-jobs/) page. ### Resource class Using `resource_class`, it is possible to specify CPU and RAM resources for each job. For a list of available resource class options, contact your system administrator. Examples of how to set a resource class: ```yaml jobs: my-build: docker: - image: cimg/base:current resource_class: xlarge steps: # ... other config ``` ```yaml jobs: my-job: machine: image: ubuntu-2404:current resource_class: large steps: # ... other config ``` ```yaml jobs: build: # name of your job machine: image: 'windows-server-2022-gui:current' resource_class: windows.medium steps: # ... other config ``` ```yaml jobs: my-job: machine: image: ubuntu-2404:current resource_class: arm.medium steps: # ... other config ``` On CircleCI Server, use `image: default` for the Linux VM, `image: windows-default` for Windows, and `image: arm-default` for Arm. * Read more about resource classes on the [Resource Class Overview](https://circleci.com/docs/guides/server/execute/resource-class-overview/) page. ## Optimize your configuration files ### Dynamic configuration Use dynamic configuration to generate CircleCI config files dynamically, depending on specific pipeline values or file paths. Dynamic config allows you to: * Execute conditional workflows/commands. * Pass pipeline parameter values and/or generate additional configuration. Read more about dynamic configuration on the [Dynamic Configuration](https://circleci.com/docs/guides/server/orchestrate/dynamic-config/) overview page. ### Orbs Orbs are reusable packages of parameterizable configuration that can be used in any project. Use orbs to: * Simplify configuration (`.circleci/config.yml`) * Automate repeated processes * Accelerate project setup * Simplify integration with third-party tools. Read more about orbs on the [Orbs Overview](https://circleci.com/docs/orbs/use/orb-intro/) page. ## See also * [Persisting Data](https://circleci.com/docs/guides/server/optimize/persist-data/) * For a complete list of customizations, view the [Configuration Reference](https://circleci.com/docs/reference/configuration-reference/) page. * For information about how Yarn can potentially speed up builds and reduce errors, view the [Caching Dependencies](https://circleci.com/docs/guides/server/optimize/caching/#yarn-node) page. * Coinbase published an article titled [Continuous Integration at Coinbase: How we optimized CircleCI for speed and cut our build times by 75%](https://blog.coinbase.com/continuous-integration-at-coinbase-how-we-optimized-circleci-for-speed-cut-our-build-times-by-378c8b1d7161).