feat(image): support --change on import

cmd/nerdctl/image/image_import.go

@@ -45,6 +45,7 @@ func ImportCommand() *cobra.Command {
 
 	cmd.Flags().StringP("message", "m", "", "Set commit message for imported image")
 	cmd.Flags().String("platform", "", "Set platform for imported image (e.g., linux/amd64)")
+	cmd.Flags().StringArrayP("change", "c", nil, "Apply Dockerfile instruction to the created image")
 	return cmd
 }
 
@@ -61,6 +62,10 @@ func importOptions(cmd *cobra.Command, args []string) (types.ImageImportOptions,
 	if err != nil {
 		return types.ImageImportOptions{}, err
 	}
+	changes, err := cmd.Flags().GetStringArray("change")
+	if err != nil {
+		return types.ImageImportOptions{}, err
+	}
 	var reference string
 	if len(args) > 1 {
 		reference = args[1]
@@ -97,6 +102,7 @@ func importOptions(cmd *cobra.Command, args []string) (types.ImageImportOptions,
 		Reference: reference,
 		Message:   message,
 		Platform:  platform,
+		Changes:   changes,
 	}, nil
 }
 

cmd/nerdctl/image/image_import_linux_test.go

@@ -23,6 +23,7 @@ import (
 	"net/http"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 	"testing"
 
@@ -45,6 +46,20 @@ func minimalRootfsTar(t *testing.T) *bytes.Buffer {
 	return buf
 }
 
+// minimalImageArchiveTar returns a tar that looks like a standard image archive
+// (it carries a manifest.json), used to exercise the --change rejection path.
+func minimalImageArchiveTar(t *testing.T) *bytes.Buffer {
+	t.Helper()
+	buf := new(bytes.Buffer)
+	tw := tar.NewWriter(buf)
+	content := []byte("[]")
+	assert.NilError(t, tw.WriteHeader(&tar.Header{Name: "manifest.json", Size: int64(len(content)), Mode: 0644}))
+	_, err := tw.Write(content)
+	assert.NilError(t, err)
+	assert.NilError(t, tw.Close())
+	return buf
+}
+
 func TestImageImportErrors(t *testing.T) {
 	nerdtest.Setup()
 
@@ -143,6 +158,55 @@ func TestImageImport(t *testing.T) {
 				}
 			},
 		},
+		{
+			Description: "image import with change",
+			Cleanup: func(data test.Data, helpers test.Helpers) {
+				helpers.Anyhow("rmi", "-f", data.Identifier())
+			},
+			Command: func(data test.Data, helpers test.Helpers) test.TestableCommand {
+				cmd := helpers.Command("import",
+					"--change", `CMD ["echo","hi"]`,
+					"--change", "ENV FOO=bar",
+					"--change", "WORKDIR /srv",
+					"--change", "EXPOSE 8080",
+					"-", data.Identifier())
+				cmd.Feed(bytes.NewReader(minimalRootfsTar(t).Bytes()))
+				return cmd
+			},
+			Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
+				identifier := data.Identifier() + ":latest"
+				return &test.Expected{
+					Output: expect.All(
+						func(stdout string, t tig.T) {
+							img := nerdtest.InspectImage(helpers, identifier)
+							assert.Assert(t, img.Config != nil)
+							assert.DeepEqual(t, img.Config.Cmd, []string{"echo", "hi"})
+							assert.Assert(t, slices.Contains(img.Config.Env, "FOO=bar"))
+							assert.Equal(t, img.Config.WorkingDir, "/srv")
+							_, ok := img.Config.ExposedPorts["8080/tcp"]
+							assert.Assert(t, ok)
+						},
+					),
+				}
+			},
+		},
+		{
+			Description: "image import --change rejected for a standard image archive",
+			// nerdctl-only: Docker's import treats any tarball as a rootfs and has
+			// no standard-image-archive rejection.
+			Require: require.Not(nerdtest.Docker),
+			Command: func(data test.Data, helpers test.Helpers) test.TestableCommand {
+				cmd := helpers.Command("import", "--change", `CMD ["echo"]`, "-", data.Identifier())
+				cmd.Feed(bytes.NewReader(minimalImageArchiveTar(t).Bytes()))
+				return cmd
+			},
+			Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
+				return &test.Expected{
+					ExitCode: expect.ExitCodeGenericFail,
+					Errors:   []error{errors.New("filesystem archive")},
+				}
+			},
+		},
 		{
 			Description: "image import with platform",
 			Cleanup: func(data test.Data, helpers test.Helpers) {

docs/command-reference.md

@@ -970,10 +970,9 @@ Usage: `nerdctl import [OPTIONS] file|URL|- [REPOSITORY[:TAG]]`
 Flags:
 
 - :whale: `-m, --message`: Set commit message for imported image
+- :whale: `-c, --change`: Apply a Dockerfile instruction to the created image, e.g. `--change 'CMD ["echo"]'`. Repeatable. Supported instructions: `CMD`, `ENTRYPOINT`, `ENV`, `EXPOSE`, `LABEL`, `USER`, `VOLUME`, `WORKDIR`, `STOPSIGNAL`.
 - :nerd_face: `--platform=(linux/amd64|linux/arm64|...)`: Set platform for the imported image
 
-Unimplemented `docker import` flags: `--change`
-
 ### :whale: nerdctl tag
 
 Create a tag TARGET\_IMAGE that refers to SOURCE\_IMAGE.

go.mod

@@ -27,6 +27,7 @@ require (
 	github.com/docker/cli v29.8.1+incompatible //gomodjail:unconfined
 	github.com/docker/go-connections v0.8.1 //gomodjail:unconfined
 	github.com/docker/go-units v0.5.0
+	github.com/moby/buildkit v0.33.0
 	github.com/moby/moby/client v0.6.0 //gomodjail:unconfined
 	github.com/moby/moby/v2 v2.0.0-beta.24 //gomodjail:unconfined
 	github.com/moby/sys/mount v0.3.5 //gomodjail:unconfined
@@ -90,20 +91,21 @@ require (
 	//gomodjail:unconfined
 	github.com/containerd/ttrpc v1.2.9 // indirect
 	//gomodjail:unconfined
-	github.com/docker/docker-credential-helpers v0.9.3 // indirect
+	github.com/docker/docker-credential-helpers v0.9.8 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
 	github.com/moby/locker v1.0.1 // indirect
 	github.com/moby/moby/api v1.56.0 // indirect
 	//gomodjail:unconfined
 	github.com/moby/sys/mountinfo v0.7.2 // indirect
 	github.com/moby/sys/symlink v0.3.0 // indirect
-	golang.org/x/exp v0.0.0-20250711185948-6ae5c78190dc // indirect
+	golang.org/x/exp v0.0.0-20260603202125-055de637280b // indirect
 )
 
 require (
 	cyphar.com/go-pathrs v0.2.5 // indirect
 	github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect
 	github.com/ProtonMail/go-crypto v1.4.1 // indirect
+	github.com/agext/levenshtein v1.2.3 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	//gomodjail:unconfined
 	github.com/cilium/ebpf v0.22.0 // indirect
@@ -146,6 +148,7 @@ require (
 	github.com/petermattis/goid v0.0.0-20240813172612-4fcff4a6cae7 // indirect
 	github.com/philhofer/fwd v1.2.0 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
+	github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 // indirect
 	//gomodjail:unconfined
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.1 // indirect
 	github.com/sasha-s/go-deadlock v0.3.5 // indirect
@@ -157,6 +160,7 @@ require (
 	github.com/stefanberger/go-pkcs11uri v0.0.0-20230803200340-78284954bff6 // indirect
 	//gomodjail:unconfined
 	github.com/tinylib/msgp v1.3.0 // indirect
+	github.com/tonistiigi/go-csvvalue v0.0.0-20240814133006-030d3b2625d0 // indirect
 	//gomodjail:unconfined
 	github.com/vbatts/tar-split v0.12.3 // indirect
 	github.com/xhit/go-str2duration/v2 v2.1.0 // indirect

go.sum

@@ -14,6 +14,8 @@ github.com/Microsoft/hcsshim v0.15.0-rc.4 h1:aZFX4LH0S20Lgjq0wG61StIClj7im4yzrxI
 github.com/Microsoft/hcsshim v0.15.0-rc.4/go.mod h1:BA9CBztgu4h/6Jsvo1O1M4qjWw09PoYpaEYgexPE578=
 github.com/ProtonMail/go-crypto v1.4.1 h1:9RfcZHqEQUvP8RzecWEUafnZVtEvrBVL9BiF67IQOfM=
 github.com/ProtonMail/go-crypto v1.4.1/go.mod h1:e1OaTyu5SYVrO9gKOEhTc+5UcXtTUa+P3uLudwcgPqo=
+github.com/agext/levenshtein v1.2.3 h1:YB2fHEn0UJagG8T1rrWknE3ZQzWM06O8AMAatNn7lmo=
+github.com/agext/levenshtein v1.2.3/go.mod h1:JEDfjyjHDjOF/1e4FlBE/PkbqA9OfWu2ki2W0IB5558=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/cilium/ebpf v0.22.0 h1:v2ktp0roffpMOj2MMf3idtCQZOsAoC4BJbAJN+ke2bY=
@@ -89,8 +91,8 @@ github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxK
 github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/docker/cli v29.8.1+incompatible h1:qYL1bCp6cRw2SB1xmLlIOPyV171dilw9W2Jew38vy9c=
 github.com/docker/cli v29.8.1+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
-github.com/docker/docker-credential-helpers v0.9.3 h1:gAm/VtF9wgqJMoxzT3Gj5p4AqIjCBS4wrsOh9yRqcz8=
-github.com/docker/docker-credential-helpers v0.9.3/go.mod h1:x+4Gbw9aGmChi3qTLZj8Dfn0TD20M/fuWy0E5+WDeCo=
+github.com/docker/docker-credential-helpers v0.9.8 h1:bIREROb7So6PRlq6KTtdS9MPEjC29OQRkFNlvK2OX8Q=
+github.com/docker/docker-credential-helpers v0.9.8/go.mod h1:v1S+hepowrQXITkEfw6o4+BMbGot02wiKpzWhGUZK6c=
 github.com/docker/go-connections v0.8.1 h1:JibmG5hULs5qXSr/cp/w3Pw5fZuStt4MOHMUExb29/M=
 github.com/docker/go-connections v0.8.1/go.mod h1:no1qkHdjq7kLMGUXYAduOhYPSJxxvgWBh7ogVvptn3Q=
 github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
@@ -127,8 +129,8 @@ github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
-github.com/google/pprof v0.0.0-20250820193118-f64d9cf942d6 h1:EEHtgt9IwisQ2AZ4pIsMjahcegHh6rmhqxzIRQIyepY=
-github.com/google/pprof v0.0.0-20250820193118-f64d9cf942d6/go.mod h1:I6V7YzU0XDpsHqbsyrghnFZLO1gwK6NPTNvmetQIk9U=
+github.com/google/pprof v0.0.0-20260402051712-545e8a4df936 h1:EwtI+Al+DeppwYX2oXJCETMO23COyaKGP6fHVpkpWpg=
+github.com/google/pprof v0.0.0-20260402051712-545e8a4df936/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
@@ -165,6 +167,8 @@ github.com/minio/sha256-simd v1.0.1 h1:6kaan5IFmwTNynnKKpDHe6FWHohJOHhCPchzK49dz
 github.com/minio/sha256-simd v1.0.1/go.mod h1:Pz6AKMiUdngCLpeTL/RJY1M9rUuPMYujV5xJjtbRSN8=
 github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y=
 github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
+github.com/moby/buildkit v0.33.0 h1:zBbt1FiMcTB/oFg1iCNcKa83k5Rn8MGcVjXFIcfYhuQ=
+github.com/moby/buildkit v0.33.0/go.mod h1:uNKSZnfMk1aSa18JiCR5BT68M/3jIDGo6XuAByUK3ek=
 github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
 github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
 github.com/moby/locker v1.0.1 h1:fOXqR41zeveg4fFODix+1Ch4mj/gT0NE1XJbp/epuBg=
@@ -225,6 +229,8 @@ github.com/philhofer/fwd v1.2.0 h1:e6DnBTl7vGY+Gz322/ASL4Gyp1FspeMvx1RNDoToZuM=
 github.com/philhofer/fwd v1.2.0/go.mod h1:RqIHx9QI14HlwKwm98g9Re5prTQ6LdeRQn+gXJFxsJM=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 h1:GFCKgmp0tecUJ0sJuv4pzYCqS9+RGSn52M3FUwPs+uo=
+github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10/go.mod h1:t/avpk3KcrXxUnYOhZhMXJlSEyie6gQbtLq5NM3loB8=
 github.com/prometheus/procfs v0.21.1 h1:GljZCt+zSTS+NZq88cyQ1LjZ+RCHp3uVuabBWA5+OJI=
 github.com/prometheus/procfs v0.21.1/go.mod h1:aB55Cww9pdSJVHk0hUf0inxWyyjPogFIjmHKYgMKmtY=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
@@ -257,6 +263,8 @@ github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWD
 github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
 github.com/tinylib/msgp v1.3.0 h1:ULuf7GPooDaIlbyvgAxBV/FI7ynli6LZ1/nVUNu+0ww=
 github.com/tinylib/msgp v1.3.0/go.mod h1:ykjzy2wzgrlvpDCRc4LA8UXy6D8bzMSuAF3WD57Gok0=
+github.com/tonistiigi/go-csvvalue v0.0.0-20240814133006-030d3b2625d0 h1:2f304B10LaZdB8kkVEaoXvAMVan2tl9AiK4G0odjQtE=
+github.com/tonistiigi/go-csvvalue v0.0.0-20240814133006-030d3b2625d0/go.mod h1:278M4p8WsNh3n4a1eqiFcV2FGk7wE5fwUpUom9mK9lE=
 github.com/vbatts/tar-split v0.12.3 h1:Cd46rkGXI3Td4yrVNwU8ripbxFaQbmesqhjBUUYAJSw=
 github.com/vbatts/tar-split v0.12.3/go.mod h1:sQOc6OlqGCr7HkGx/IDBeKiTIvqhmj8KffNhEXG4Nq0=
 github.com/vishvananda/netlink v1.3.1 h1:3AEMt62VKqz90r0tmNhog0r/PpWKmrEShJU0wJW6bV0=
@@ -301,8 +309,8 @@ golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v
 golang.org/x/crypto v0.33.0/go.mod h1:bVdXmD7IV/4GdElGPozy6U7lWdRXA4qyRVGJV57uQ5M=
 golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
 golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
-golang.org/x/exp v0.0.0-20250711185948-6ae5c78190dc h1:TS73t7x3KarrNd5qAipmspBDS1rkMcgVG/fS1aRb4Rc=
-golang.org/x/exp v0.0.0-20250711185948-6ae5c78190dc/go.mod h1:A+z0yzpGtvnG90cToK5n2tu8UJVP2XUATh+r+sfOOOc=
+golang.org/x/exp v0.0.0-20260603202125-055de637280b h1:v1uXiEBHo8QA0LiGCo7UgHMzHT4Kdfpl2zmtH5vaP1Q=
+golang.org/x/exp v0.0.0-20260603202125-055de637280b/go.mod h1:d2fgXJLVs4dYDHUk5lwMIfzRzSrWCfGZb0ZqeLa/Vcw=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=

pkg/api/types/import_types.go

@@ -28,4 +28,7 @@ type ImageImportOptions struct {
 	Reference string
 	Message   string
 	Platform  string
+	// Changes holds Dockerfile-style instructions (--change) applied to the
+	// imported image's config, e.g. `CMD ["echo"]` or `ENV FOO=bar`.
+	Changes []string
 }

pkg/cmd/image/import.go

@@ -49,6 +49,12 @@ import (
 )
 
 func Import(ctx context.Context, client *containerd.Client, options types.ImageImportOptions) (string, error) {
+	// Validate --change before any layer work, so a syntactic error fails fast
+	// instead of after the (possibly large) layer is compressed and committed.
+	if err := applyChanges(&ocispec.ImageConfig{}, options.Changes); err != nil {
+		return "", err
+	}
+
 	prefix := options.Reference
 	if prefix == "" {
 		prefix = fmt.Sprintf("import-%s", time.Now().Format("2006-01-02"))
@@ -111,6 +117,12 @@ func ensureOCIArchive(ctx context.Context, client *containerd.Client, r io.ReadC
 
 	combined := io.NopCloser(io.MultiReader(buf, r))
 	if isStandardArchive {
+		// A standard image archive already carries its own config; --change only
+		// applies to a filesystem (rootfs) import, which builds a fresh config.
+		if len(options.Changes) > 0 {
+			r.Close()
+			return nil, func() {}, fmt.Errorf("--change is only supported when importing a filesystem archive, not a standard image archive")
+		}
 		return combined, func() { r.Close() }, nil
 	}
 
@@ -268,6 +280,11 @@ func buildImageConfig(diffID digest.Digest, options types.ImageImportOptions) ([
 		}},
 	}
 
+	// Apply any --change instructions to the fresh config.
+	if err := applyChanges(&imgConfig.Config, options.Changes); err != nil {
+		return nil, "", err
+	}
+
 	configJSON, err := json.Marshal(imgConfig)
 	if err != nil {
 		return nil, "", err