We use cookies to understand how people use Depot.
← All Posts

Now available: Debug your build context

Written by
Kyle Galbraith
Published on
15 December 2023
Inside of build insights you can now see what is in your build context on every build. Knowing what is in your context can help you discover unexpected files your including in your build and final image.
Now available: Debug your build context banner

Today, we're releasing a new context tab as part of Build Insights. The new tab lets you visualize what exactly was in your build context when the build ran. The first time you run a build with no cache, you can see the full context that is transferred to Depot. On subsequent builds, you can see the modifications to the context.

With the context tab you can quickly identify the total size of your context, the size of each file inside, and how long each file took to transfer to Depot.

What is build context?

Build context is the collection of files that your Docker image build accesses. It's referenced as a positional argument after either a docker build or depot build. The most common build context folks leverage is their current working directory:

docker build .

In this case, the . is the build context. All files in the current working directory will be sent to the builder as part of the build.

If you want to exclude files from the build context, you can use a .dockerignore file. This file is similar to a .gitignore file, but instead of ignoring files from Git, it ignores files from the build context. For example, we probably want to ignore the .git folder and our README.md as we don't need them in our actual Docker image build.


The first time you run a build with no cache, the entire build context is passed up to Depot. But on subsequent builds, only changes to the build context, like your source code changes, are passed up. So, if you have a large build context but only a few files have changed, we only need to sync those files after your first build.

Visualizing what is in your build context with Depot

Build context can impact your build and final Docker image. First, the larger your build context, the longer it takes to transfer to a remote build service (see our post on optimizing builds for Depot), slowing down your build. Second, a bloated build context can lead to increased Docker image sizes because you can inadvertently COPY files into your image that you didn't expect to be in your context.

But debugging these problems has always been challening. Because understanding what is in your build context usually requires using tools like dive or building out-of-band images that mount your build context to inspect it.

But now, with the new context tab in your Build Insights, you can quickly see what is in your build context on every build.

Example of build context in Depot

The build context view inside your build details shows you the total size of the context that was passed up to Depot, how large each file was, and individual file transfer times. This allows you to quickly debug why your build is slow or why your final Docker image is larger than expected.


Debugging Docker image builds has always been challenging. Our goal is to make not only your builds faster but also your entire lifecycle around them faster as well. This includes making them easier to debug by surfacing the data you need to understand what is happening. With the new context tab, we are surfacing precisely what was transferred in your build context to Depot.

But, we're always looking for additional items that we can surface or help you take action on that avoids additional developer loops. If you have any ideas, please reach out and let us know. If you are new to Depot and want to try things out, you can sign up and get started today with a free trial.

Build Docker containers 40x faster
Get started for free →