Initialize Phase
Host-side hooks that run before the container is built or created, preparing only the files and directories the container definition expects.
- Kind
- Lifecycle
- Domain
- Environment & Tooling
- Applies at
.devcontainer/lifecycle/initialize.d/- Status
- Stable
- Source · managed
.devcontainer/lifecycle/initialize.d/README.md
01 Defines
The initializeCommand phase: scripts in initialize.d/ that run on the host, before the image is built, to create host-side state that a mount or build depends on.
02 Applies when
- A mount needs a host-side directory or file to exist before the container is created.
- A required environment file is created from a repository-provided example before container creation reads it.
03 Boundaries
- Nothing here may assume the container shell, the mounted workspace, or tooling provided by the environment.
- Project dependency operations and in-container tool installs belong in later phases or features.
- Interactive sign-in flows are out of scope.
Expected behaviour
- 01Scripts run on the host, not in the container.
- 02The phase may run more than once, so every script is safe to repeat.
- 03The phase holds only what the container definition needs before creation.
Behaviour#
initializeCommand is the only phase that runs outside the container. It runs
before the image is built and the container is created, and the Dev Containers
tooling may run it again on later rebuilds. That makes it the narrowest phase:
it exists so that host-side paths are in place when the container definition
refers to them, and for nothing else.
If a task needs the container shell, the mounted workspace, or a tool the environment provides, it belongs in On-Create Phase or later.
Good uses
- Creating a persistent host-side cache directory, such as
.cache/bazel, before it is mounted - Creating a required environment file from a checked-in example
- Pre-creating a file a mount expects, such as
.devcontainer/aws/config
Avoid
npm install,pnpm install,dotnet restore, orterraform init- Installing Hugo, Node, Terraform, or other in-container tools
aws sso login,gh auth login, and other interactive sign-ins
Examples#
#!/usr/bin/env bash
set -euo pipefail
mkdir -p .cache/bazel
mkdir -p is already idempotent, which is exactly the shape a host-side hook
should take: it can run on every rebuild without changing anything the second
time.
Connections