diff --git a/doc/languages-frameworks/go.section.md b/doc/languages-frameworks/go.section.md
index d98ecb1c0421..b20308c7b4ab 100644
--- a/doc/languages-frameworks/go.section.md
+++ b/doc/languages-frameworks/go.section.md
@@ -66,6 +66,25 @@ The following is an example expression using `buildGoModule`:
 
 The function `buildGoPackage` builds legacy Go programs, not supporting Go modules.
 
+::: {.warning}
+`buildGoPackage` is deprecated and will be removed for the 25.05 release.
+:::
+
+### Migrating from `buildGoPackage` to `buildGoModule` {#buildGoPackage-migration}
+
+Go modules, released 6y ago, are now widely adopted in the ecosystem.
+Most upstream projects are using Go modules, and the tooling previously used for dependency management in Go is mostly deprecated, archived or at least unmaintained at this point.
+
+In case a project doesn't have external dependencies or dependencies are vendored in a way understood by `go mod init`, migration can be done with a few changes in the package.
+
+- Switch the builder from `buildGoPackage` to `buildGoModule`
+- Remove `goPackagePath` and other attributes specific to `buildGoPackage`
+- Set `vendorHash = null;`
+- Run `go mod init <module name>` in `postPatch`
+
+In case the package has external dependencies that aren't vendored or the build setup is more complex the upstream source might need to be patched.
+Examples for the migration can be found in the [issue tracking migration withing nixpkgs](https://github.com/NixOS/nixpkgs/issues/318069).
+
 ### Example for `buildGoPackage` {#example-for-buildgopackage}
 
 In the following is an example expression using `buildGoPackage`, the following arguments are of special significance to the function:
diff --git a/pkgs/build-support/go/package.nix b/pkgs/build-support/go/package.nix
index 58a242a2535c..754736dfbe6e 100644
--- a/pkgs/build-support/go/package.nix
+++ b/pkgs/build-support/go/package.nix
@@ -289,4 +289,6 @@ lib.warnIf (buildFlags != "" || buildFlagsArray != "")
   "`buildFlags`/`buildFlagsArray` are deprecated and will be removed in the 24.11 release. Use the `ldflags` and/or `tags` attributes instead"
 lib.warnIf (builtins.elem "-buildid=" ldflags) "`-buildid=` is set by default as ldflag by buildGoModule"
 lib.warnIf (builtins.elem "-trimpath" GOFLAGS) "`-trimpath` is added by default to GOFLAGS by buildGoModule when allowGoReference isn't set to true"
+lib.warn '''buildGoPackage' is deprecated and will be removed for the 25.05 release.
+Please use 'buildGoModule' instead. Tips for migration can be found in the Go section of the nixpkgs manual.''
   package