docker/compose · error

output option is required when exporting to terminal

Error message

output option is required when exporting to terminal

What it means

'docker compose export' writes a container filesystem tarball; when no --output path is given and stdout is a TTY, dumping a binary tar stream to the terminal would corrupt it, so compose requires an explicit output. Non-terminal stdout (redirects/pipes) is allowed.

Source

Thrown at pkg/compose/export.go:48

)

func (s *composeService) Export(ctx context.Context, projectName string, options api.ExportOptions) error {
	return Run(ctx, func(ctx context.Context) error {
		return s.export(ctx, projectName, options)
	}, "export", s.events)
}

func (s *composeService) export(ctx context.Context, projectName string, options api.ExportOptions) error {
	projectName = strings.ToLower(projectName)

	container, err := s.getSpecifiedContainer(ctx, projectName, oneOffInclude, false, options.Service, options.Index)
	if err != nil {
		return err
	}

	if options.Output == "" {
		if s.stdout().IsTerminal() {
			return fmt.Errorf("output option is required when exporting to terminal")
		}
	} else if err := command.ValidateOutputPath(options.Output); err != nil {
		return fmt.Errorf("failed to export container: %w", err)
	}

	name := getCanonicalContainerName(container)
	s.events.On(api.Resource{
		ID:     name,
		Text:   api.StatusExporting,
		Status: api.Working,
	})

	responseBody, err := s.apiClient().ContainerExport(ctx, container.ID, client.ContainerExportOptions{})
	if err != nil {
		return err
	}

	defer func() {

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Pass --output: docker compose export myservice -o fs.tar
2. Or redirect: docker compose export myservice > fs.tar
3. Verify the resulting tar: tar -tf fs.tar | head

Example fix

# before
docker compose export web
# after
docker compose export web --output web-rootfs.tar

// API-level: require output before calling Export
if opts.Output == "" && term.IsTerminal(os.Stdout.Fd()) {
    return errors.New("--output is required in interactive terminals")
}

When it happens

Trigger: Running 'docker compose export <service>' interactively in a shell without -o/--output while stdout is a TTY.

Common situations: Interactive use of the newer export command; forgetting that unlike some commands, export defaults to requiring a target here; scripting without redirect.

Related errors

• source can not be empty
• destination can not be empty
• invalid filter '${filter}'
• --index requires one service to be selected
• arguments to --filter should be in form KEY=VAL

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