skip to content

In a GitHub Codespaces devcontainer.json, what are dev container features, and how do they differ from installing tools in a lifecycle command?

level: middleimportance: should knowfreq 30%

answer

  1. packaged install script plus metadata
  2. referenced by registry ID
  3. runs during the image build
  4. one cached layer each
  5. missing tag means latest

basics

~20 s

Features are versioned, shareable install units referenced by ID in the features object. Their scripts run as root during the image build, each as a cached layer, whereas lifecycle commands run later inside the started container.

solid answer

~40 s

A feature is a packaged `install.sh` plus a `devcontainer-feature.json`, referenced under `features` by an OCI ID such as `ghcr.io/devcontainers/features/github-cli:1`, an HTTPS tarball URL, or a local `./folder` beside `devcontainer.json`. Its value holds options, and a bare string is shorthand for the `version` option. Omitting the tag means `:latest`, so pin a major version. Features install as root while the image is built, each as its own layer, so a rebuild can reuse them from cache, and they work on top of an `image`, a Dockerfile or a Compose service. Install order follows each feature's own `installsAfter` and `dependsOn` metadata unless `overrideFeatureInstallOrder` in `devcontainer.json` sets it. Lifecycle commands run later, inside the running container from the workspace folder, once the source is present, so repository-dependent steps belong there and reusable tooling belongs in features.

go deeper

for a junior

Recall that features add tools by ID under the features object, and that the tag after the colon is the feature's own version.

for a middle

Explain that features run as root during the image build, one cached layer each, and how that differs from a lifecycle command running in the started container.

for a senior

Decide what goes in a feature, a Dockerfile or a lifecycle command for a real repository, and pin feature versions so environments do not drift between codespaces.

for a principal

Judge whether an organization should publish its own internal features or images, trading reuse and consistency across repositories against the work of maintaining and versioning them.

## What a feature is A **dev container feature** is a self-contained unit of installation code and configuration: a folder holding at least a `devcontainer-feature.json` (its ID, version, name, options and other metadata) and an `install.sh` entry point. Instead of every repository copying the same twenty lines of setup for a tool, the tool's maintainers publish a feature once and every configuration references it. In a codespace, features are how a team adds a CLI, a runtime or a library to whatever base the configuration uses, without writing a Dockerfile. The GitHub web editor for `devcontainer.json` even has a **Marketplace** tab that copies a feature's snippet into the file. Features published to a container registry are versioned and distributed the same way container images are, so the registry that serves a team's images can serve its features too. ## Referencing a feature Features are listed under the top-level `features` object, one key per feature. The key's form tells the tool where to fetch it: | Form | Example | Fetched from | |---|---|---| | OCI reference | `ghcr.io/devcontainers/features/github-cli:1` | A container registry implementing the OCI distribution specification | | HTTPS tarball | `https://example.com/releases/devcontainer-feature-tool.tgz` | A direct download | | Local folder | `./tools-feature` | A folder relative to the one holding `devcontainer.json` | Identifiers are case-insensitive and normalised to lower case. ## Options and versions - The value of each key is an object of **options**, strings or booleans, which the install script receives as environment variables at build time. An empty object `{}` means the defaults. - A bare string is shorthand for the `version` option: a value of `"1.18"` means the same as `{"version": "1.18"}`, and the feature decides what that version number selects. - The tag after the colon is the **feature's own** semantic version. If it is omitted, `:latest` is added implicitly, so the configuration can change under you when the feature is republished. Pinning a major version such as `:1` takes compatible fixes without surprises. - Some features are written for a particular Linux distribution family, so a feature that works on one base image may fail on another. ## When features run Features belong to the **image build**, not to container start-up: 1. The base is obtained: an image is pulled, a Dockerfile built, or the Compose service's image prepared. 2. Each feature's `install.sh` runs **as root** during the image build, each as **its own layer**, in an order derived from the features' `installsAfter` (soft) and `dependsOn` (hard) metadata, unless `overrideFeatureInstallOrder` in `devcontainer.json` fixes it. 3. The container is created and started with the source mounted. 4. Lifecycle commands run inside it. A feature may also contribute its own lifecycle commands; at each hook these run before the commands written in `devcontainer.json`. Because each feature is a cached layer, a normal rebuild of a codespace can reuse features already built, while `onCreateCommand` and later commands run again. A full rebuild discards the cache and runs everything from freshly pulled images. ## Features, a Dockerfile or a lifecycle command? | Need | Best place | Why | |---|---|---| | A common tool or runtime many repositories use | Feature | Maintained once, versioned, cached as a layer | | An unusual system package or file baked into the image | Dockerfile | Full control of the image build | | Dependencies read from the repository's own files | Lifecycle command | Needs the source tree, which exists only after the container starts | | Per-user setup using personal credentials | `postCreateCommand` | Runs after the codespace is assigned to its user | The distinction matters for speed and correctness. A tool installed in `postCreateCommand` is installed again in every new codespace and, unlike a feature, is never part of a cached image layer or a prebuild snapshot. A dependency install placed in a feature, conversely, cannot see the repository's lock files, because the build happens before the source is mounted. ## Pitfalls - Leaving the tag off and getting a different feature release next month. - Adding a feature to the file and expecting existing codespaces to have it: they need the change pulled in and the container rebuilt. - Ordering problems between features that depend on each other, fixed with `overrideFeatureInstallOrder` rather than by reordering keys. - Combining a feature with a minimal base image it was never written for; check which distributions a feature supports before adopting it. - Expecting a feature to install the project's own dependencies: it runs before the source is mounted, so that job belongs to a lifecycle command.

  • Can a feature run commands after the container has started?
    Yes. A feature's own metadata can declare lifecycle hooks such as `onCreateCommand` or `postCreateCommand`. At each hook, commands contributed by features run in feature installation order and always before the commands written in `devcontainer.json`, from the workspace folder like any other lifecycle command.
  • You added a feature to devcontainer.json, but your existing codespace still lacks the tool. Why?
    Features are installed during the image build, so a codespace created before the change has none. Pull the change and rebuild the container; a normal rebuild reuses cached layers, while `gh codespace rebuild --full` discards the cache and pulls fresh images. New codespaces get the feature automatically.

  • Features are installed again every time the codespace starts
  • Omitting a feature's version tag pins whatever version was first installed
  • installsAfter is written in devcontainer.json to order features
  • Features only work on top of the default Codespaces image
  • A feature's install script runs as the non-root remote user