docker/compose · error

'models' support requires Docker Model plugin

Error message

'models' support requires Docker Model plugin

What it means

When a compose project uses 'models' (AI model services), compose shells out to the Docker Model plugin located via the CLI plugin manager. If plugin resolution returns NotFound, compose throws this before any model work starts — the plugin simply is not installed on this machine.

Source

Thrown at pkg/compose/model.go:85

			return mdlAPI.ConfigureModel(ctx, config, s.events)
		})
	}
	return eg.Wait()
}

type modelAPI struct {
	path    string
	env     []string
	prepare func(ctx context.Context, cmd *exec.Cmd) error
	cleanup func()
	version string
}

func (s *composeService) newModelAPI(project *types.Project) (*modelAPI, error) {
	dockerModel, err := manager.GetPlugin("model", s.dockerCli, &cobra.Command{})
	if err != nil {
		if errdefs.IsNotFound(err) {
			return nil, fmt.Errorf("'models' support requires Docker Model plugin")
		}
		return nil, err
	}
	if dockerModel.Err != nil {
		return nil, fmt.Errorf("failed to load Docker Model plugin: %w", dockerModel.Err)
	}
	endpoint, cleanup, err := s.propagateDockerEndpoint()
	if err != nil {
		return nil, err
	}
	return &modelAPI{
		path:    dockerModel.Path,
		version: dockerModel.Version,
		prepare: func(ctx context.Context, cmd *exec.Cmd) error {
			return s.prepareShellOut(ctx, project.Environment, cmd)
		},
		cleanup: cleanup,
		env:     append(project.Environment.Values(), endpoint...),

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Install/enable the Docker Model plugin (Docker Desktop includes it; on CLI check `docker model --help` and install the plugin)
2. Verify with: docker model ls — if that fails, the plugin is missing too
3. If AI features are unwanted, remove the models section from the compose file

Example fix

# before (compose.yaml)
models:
  ai-agent:
    model: ai/llama3

# after — remove the block when the model plugin is not available
# (or install the plugin and keep it)

// pre-flight: can we resolve the model plugin?
if _, err := manager.GetPlugin("model", cli, &cobra.Command{}); errdefs.IsNotFound(err) {
    return errors.New("install the Docker Model plugin or remove 'models' from the compose file")
}

if err := compose.Up(ctx, project, opts); err != nil {
    if strings.Contains(err.Error(), "requires Docker Model plugin") {
        // guide user to install plugin or strip models section
    }
}

When it happens

Trigger: A compose file with models/ai service definitions run on a Docker installation without the 'model' CLI plugin (plain Docker Engine without Desktop, or a Linux install where the plugin was never added).

Common situations: Developers on Linux Docker Engine trying compose files authored on Docker Desktop; CI images with bare dockerd; users who uninstalled or never installed the model plugin.

Related errors

• failed to load Docker Model plugin: %w
• error checking docker-model status: %w
• error checking available models: %w
• error unmarshalling available models: %w
• no available sync implementation

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/0b67a09229a0a023. Report an issue: GitHub.