In a GitHub Codespaces devcontainer.json, what are dev container features, and how do they differ from installing tools in a lifecycle command?
answer
- packaged install script plus metadata
- referenced by registry ID
- runs during the image build
- one cached layer each
- missing tag means latest
basics
~20 sFeatures 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 sA 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
Recall that features add tools by ID under the features object, and that the tag after the colon is the feature's own version.
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.
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.
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