>My package really does depend on the latest patch release!
> Even in the event that your packages code is only correct with a specific patch release, I still think its wrong to put that version in the go directive unless it cannot be compiled with any other version.
I'm not a go user, but this strikes me as an over-reaction. If your code is only correct with a specific patch release, then it really is your business to make that so. If someone downstream wants to use library_method_broadly_correct and not library_method_correct_only_with_latest, then downstream should patch your source to allow them to do something unsupported. That becomes their problem. If this is likely to be a significant problem that will affect many users, then this is a codesmell warning you that you've probably got two libraries which you're just jumbling together into one: the solution isn't to falsely gate a safe function behind a high dependency version, nor to falsely release a function to people who can't use it safely, but to publish each with its own requirements expressly stated.
That part struck me as well. I agree with the premise that the field should represent the minimum supported version, but I don’t understand the argument that it shouldn’t be set to the minimum supported version that works. That’s the point of a minimum supported version field.
I'm struggling to think of a scenario where bumping the minimum Go version you support would be essential to fixing a bug though, because that would imply a massive Golang bug and AFAIK it's pretty stable.
And if it was a massive Golang bug, then maybe everyone needs to upgrade anyway.
Or not a Golang bug at all but rather a new Golang feature that the developer chose to use rather than trying to be backward compatible with some older Golang versions.
I think "minimum supported version" is a specific enough qualifier on its own. Whether or not it works on my favorite earlier version, actually supporting that version and making sure to maintain compatibility is more work for the maintainer.
I can admit that part was maybe a bit extreme :) fortunately in practice this would be a pretty rare situation IME due to how compatible Go is across versions.
I’m afraid setting a version lower than the one you’re using means you have to setup a CI of some kind to verify compilation does indeed work for previous versions of go.
Maybe that’s why some author do not bother and put the version they are using (though I do agree it is a bad practice indeed).
In other ecosystems, I could see how this could be a problem, but I don’t think I’ve ever had a problem with a Go upgrade.
What’re the actual, practical results of a package pushing you towards a higher go version that you wouldn’t otherwise have adopted right away? Why is this actually important to avoid beyond “don’t tell me what to do”?
The author fails to mention any of the negative effects they experience due to this go version selection. They say that the effect is "viral" but don't give any concrete examples of why it's a bad thing to keep your toolchain up to date
It forces a change, where none is called for. Compatibility works both ways. What doesn't matter to me the lib dev, may for matter for someone else.
The world is built on portable, flexible code, and pinning to something unnecessarily, breaks that one small part of the world.
It's adding an unnecessary requirement. Life is hard enough.
One of the key advantages of Go is its very compatible, you can compile and run early versioned code on the latest compiler without concern and it will just run with less bugs and faster due to all the advancements over time. I don't like being forced to upgrade my tooling until I choose the upgrade but in Go's case its usually trivial.
Anyone with an older toolchain is free to fork it on github, test with the older version, and CI to the project that tests with the older version, and submit a patch, too!
This may not get the project as many users, but not everyone who writes a 50 line project is trying to figure out which versions it supports and setting up full test matrices either.
Not a Go dev, but I typically set up a CI with the oldest toolchains I support (usually a debian release), and only bump those versions when I really need something from the latest versions. Locally I build with the most recent tools. This ensures good enough coverage for very little work, as I notice when I start using something that's newer and can bump the toolchain accordingly.
Sure, but if you start a new small project and throw it on GitHub, it's not totally insane to just put the version you tested. Just because someone put up their tiny library doesn't mean they've put in the effort to figure out which version they need.
I am missing this part too. I can't really say ever having a problem upgrading go to the latest version. Now with "go fix", a lot of features are even improved automatically.
I used to see supporting multiple versions of Python as an expensive chore... and then I learned how to use the GitHub Actions matrix feature and supporting multiple versions is suddenly easy - my test suites are comprehensive enough that if they pass I'm confident it will work on that version.
Or, I have only tested my library on this version, and nothing lower.
> Even in the event that your packages code is only correct with a specific patch release, I still think its not always right to put that version in the go directive unless it cannot be compiled with any other version.
This just makes me shiver. Imagine releasing a library with a version number slightly lower because of this post, it compiles, but there is a bug that brings down production...
This is also a ticking bomb for the Go ecosystem due to how the 1.0 guarantee was updated. Originally, the guarantee was they would never make a language change that altered behavior in a breaking way, ever. But when the change to variables in the for loop was introduced, they changed the compiler to interpret the code differently based on the go.mod version of that package. So far, we've been lucky to only have changes everyone seems to have liked. But that could change in the future since the Go maintainers have made it clear there won't be a v2 of Go, they'll just make any breaking changes dependent on the go.mod version.
This is made even worse by the golang.org/x packages updating their minimum Go version without any other changes to the code that require that bump. It ripples through all projects that have any dependencies on those packages, and it forces everyone to choose between security updates and backward compatibility.
This just got me. Datadog decided that they only support the current and last major versions of Go. So, 1.26 and 1.25. But in my cause we're still on 1.24.13 which was released by the Go team less than two months ago.
So upgrade to 1.25? What reason could you possibly have to be so far behind?
I can understand staying one version behind latest, to not be exposed to brand new bugs, which do happen, but staying two versions behind is pointless.
Using a release less than two months is hardly “so far behind”. The 1.24 series had considerable regressions that have taken a number of patch releases to fix, it stands to reason that the same would be true of newer releases. Given there's still miscompilations getting fixed as late as 1.25.8, and 1.25 brought in large changesets for the new experimental GC, sticking it out while 1.24 is still getting patches a mere handful of weeks ago is not unreasonable.
My solution for this is just use the current latest, or latest-1. There’s no reason not to. If your code is somehow stuck with an old version of Go, it should be considered a high priority bug, this is not normal.
I've seen this misconception so many times in open source projects - commits just bumping the version in go.mod to 'get the latest performance and security improvements.' Like no, that's not how it works, you just made your code compile with fewer compiler versions for no reason.
I think the directive could have been named better though, maybe something like min_version.
The transitive dependency case is what makes this painful in practice. You’re not even choosing that library it’s three levels deep in your dependency tree, and suddenly CI fails because some maintainer ran `go get go@latest` on a Saturday.
Unless I am mistaken or had some other fluke it will also just happily download the old version and build with that, even if there was a vulnerability, which has mostly led me to always bumping to the latest release when I touch it.
Someone n another thread mentioned the `toolchain` command, maybe I should look into this again.
Weird that this needs to be said. I’m not familiar with the Go ecosystem, but there is usually a natural incentive for library developers to reach more people, which means you’d want to support the oldest feasible version. If you don’t do that then someone will develop a better library which does support an older version. Is that not happening here?
What the article does not say is that if you don't have a recent enough version, by default, Go automatically downloads a more recent toolchain. So, for most users, this is transparent.
However, this behavior can be disabled (for example, when building for a Linux distribution).
> The version is the minimum version your project can be compiled with.
No, it's the minimum version my project is tested with.
> This means when you put a version like 1.25.7, you are deciding for everyone that imports you, transitively or directly, that they MUST be on Go 1.25.7+ to compile their project.
That is fine. This isn't Python or Java, you have no reason to ever be more than one version behind the current release. Just upgrade, it's painless.
> The fact that it defaults to the latest version is just a bad default that people should change.
Thanks for the link! I could have sworn this was "fixed" and was surprised testing 1.26.1 showed the same (IMO bad) behavior! Didn't realize there was a revert. https://github.com/golang/go/issues/77923 looks like a hopeful path forward.
I think only languages which are still in beta have that kind of back compatibility. If a language breaks compatibility every two years (roughly Debian’s release schedule), it’s a toy, not a tool.
I always stay up with the latest go releases and if I am touching one of my packages that are set to lower in go.mod, I update it. It is an easy maintenance task to make sure I am keeping up with the latest standard library and tooling changes and improvements.
Could there be a user dialog prompt about the suggested version and some control flow that allows people to manually override during installation as a happy medium between these approaches
> Its not your responsibility to ensure transitive importers of your library are on the latest version of Go. Don't make that decision for them.
and yet the Go maintainers did not include or build (in the future) a tool that determined the minimum version of Go that your application can be compiled in.
In go, `go mod init` and `go get go@latest` (both recommended commands), both set a 'go <latest-version>' stanzas. In go, you _must_ set a minimum required version.
If you type 'cargo init', you will get 'edition = "2024"', but no 'rust-version'.
The situation is different because rust does not require a 'rust-version' in Cargo.toml, and in practice most crates do not have one, while in go it is required you specify a minimum version, there's no automation to set it to the true minimum, and most projects update it incorrectly in practice (because the go cli updates it incorrectly for you).
I think Rust is slightly different in practice even if they behave the same technically. I'm not sure Rust lets you even set the MSRV to a specific patch which is the biggest annoyance with Go; if they do it's so uncommon I've at least never seen it. And I don't believe any Rust tooling encourages you to set the MSRV to <latest Rust version> like tools in the Go ecosystem do.
>My package really does depend on the latest patch release!
> Even in the event that your packages code is only correct with a specific patch release, I still think its wrong to put that version in the go directive unless it cannot be compiled with any other version.
I'm not a go user, but this strikes me as an over-reaction. If your code is only correct with a specific patch release, then it really is your business to make that so. If someone downstream wants to use library_method_broadly_correct and not library_method_correct_only_with_latest, then downstream should patch your source to allow them to do something unsupported. That becomes their problem. If this is likely to be a significant problem that will affect many users, then this is a codesmell warning you that you've probably got two libraries which you're just jumbling together into one: the solution isn't to falsely gate a safe function behind a high dependency version, nor to falsely release a function to people who can't use it safely, but to publish each with its own requirements expressly stated.
That part struck me as well. I agree with the premise that the field should represent the minimum supported version, but I don’t understand the argument that it shouldn’t be set to the minimum supported version that works. That’s the point of a minimum supported version field.
I'm struggling to think of a scenario where bumping the minimum Go version you support would be essential to fixing a bug though, because that would imply a massive Golang bug and AFAIK it's pretty stable.
And if it was a massive Golang bug, then maybe everyone needs to upgrade anyway.
Or not a Golang bug at all but rather a new Golang feature that the developer chose to use rather than trying to be backward compatible with some older Golang versions.
I think "minimum supported version" is a specific enough qualifier on its own. Whether or not it works on my favorite earlier version, actually supporting that version and making sure to maintain compatibility is more work for the maintainer.
I can admit that part was maybe a bit extreme :) fortunately in practice this would be a pretty rare situation IME due to how compatible Go is across versions.
(Blog author)
I’m afraid setting a version lower than the one you’re using means you have to setup a CI of some kind to verify compilation does indeed work for previous versions of go.
Maybe that’s why some author do not bother and put the version they are using (though I do agree it is a bad practice indeed).
Thank you for this article. If I want to be told when to upgrade, I know where to shop, i.e. Bill's Bloatware in Redmond.
Yeah, sounds like a skill issue.
How your go.mod should look:
"This module compiles with the language and runtime of go 1.24 and later, but I recommend you use at least go release 1.25.7"go get can manage this for you - https://go.dev/doc/toolchain#get
this is great and should be in the blog post
Thank you so much.
In other ecosystems, I could see how this could be a problem, but I don’t think I’ve ever had a problem with a Go upgrade.
What’re the actual, practical results of a package pushing you towards a higher go version that you wouldn’t otherwise have adopted right away? Why is this actually important to avoid beyond “don’t tell me what to do”?
One potential reason is that Go does drop support for older OSes sometimes. For example, Go 1.22 is the newest version that works with older Mac OSes.
https://go.dev/doc/go1.22#darwin
shrug maybe so. But then again, I can't say I'm too torn up about losing support for an EOL OS version.
The author fails to mention any of the negative effects they experience due to this go version selection. They say that the effect is "viral" but don't give any concrete examples of why it's a bad thing to keep your toolchain up to date
It forces a change, where none is called for. Compatibility works both ways. What doesn't matter to me the lib dev, may for matter for someone else. The world is built on portable, flexible code, and pinning to something unnecessarily, breaks that one small part of the world. It's adding an unnecessary requirement. Life is hard enough.
One of the key advantages of Go is its very compatible, you can compile and run early versioned code on the latest compiler without concern and it will just run with less bugs and faster due to all the advancements over time. I don't like being forced to upgrade my tooling until I choose the upgrade but in Go's case its usually trivial.
Anyone with an older toolchain can’t build that library of anything that depends on it.
Some environments might not even have the newer version available.
Anyone with an older toolchain is free to fork it on github, test with the older version, and CI to the project that tests with the older version, and submit a patch, too!
This may not get the project as many users, but not everyone who writes a 50 line project is trying to figure out which versions it supports and setting up full test matrices either.
Not a Go dev, but I typically set up a CI with the oldest toolchains I support (usually a debian release), and only bump those versions when I really need something from the latest versions. Locally I build with the most recent tools. This ensures good enough coverage for very little work, as I notice when I start using something that's newer and can bump the toolchain accordingly.
Sure, but if you start a new small project and throw it on GitHub, it's not totally insane to just put the version you tested. Just because someone put up their tiny library doesn't mean they've put in the effort to figure out which version they need.
Are you sure you replied to the right comment? I'm not sure how this relates to the question being asked.
I did.
If you have an older tool chain, it is on you to fix the library to build with the older tool chain, that's what open source is about!
I am missing this part too. I can't really say ever having a problem upgrading go to the latest version. Now with "go fix", a lot of features are even improved automatically.
I used to see supporting multiple versions of Python as an expensive chore... and then I learned how to use the GitHub Actions matrix feature and supporting multiple versions is suddenly easy - my test suites are comprehensive enough that if they pass I'm confident it will work on that version.
I expect this should work equally well for Go.
Or, I have only tested my library on this version, and nothing lower.
> Even in the event that your packages code is only correct with a specific patch release, I still think its not always right to put that version in the go directive unless it cannot be compiled with any other version.
This just makes me shiver. Imagine releasing a library with a version number slightly lower because of this post, it compiles, but there is a bug that brings down production...
Thanks but not thanks.
But how do you know which minimum version you need?
Install the latest version of Go and once you are finished with the library, downgrade the version of Go by one until you get a compilation error?
This is also a ticking bomb for the Go ecosystem due to how the 1.0 guarantee was updated. Originally, the guarantee was they would never make a language change that altered behavior in a breaking way, ever. But when the change to variables in the for loop was introduced, they changed the compiler to interpret the code differently based on the go.mod version of that package. So far, we've been lucky to only have changes everyone seems to have liked. But that could change in the future since the Go maintainers have made it clear there won't be a v2 of Go, they'll just make any breaking changes dependent on the go.mod version.
This is made even worse by the golang.org/x packages updating their minimum Go version without any other changes to the code that require that bump. It ripples through all projects that have any dependencies on those packages, and it forces everyone to choose between security updates and backward compatibility.
I've ranted about this before in my blog [1].
[1]: https://bmitch.net/blog/2025-06-07-go-broke-v1/
This just got me. Datadog decided that they only support the current and last major versions of Go. So, 1.26 and 1.25. But in my cause we're still on 1.24.13 which was released by the Go team less than two months ago.
Datadog won't be getting a renewal from us.
> But in my cause we're still on 1.24.13 which was released by the Go team less than two months ago.
Yes, and then one week later the entire 1.24 branch entered EOL: https://endoflife.date/go
So upgrade to 1.25? What reason could you possibly have to be so far behind?
I can understand staying one version behind latest, to not be exposed to brand new bugs, which do happen, but staying two versions behind is pointless.
Using a release less than two months is hardly “so far behind”. The 1.24 series had considerable regressions that have taken a number of patch releases to fix, it stands to reason that the same would be true of newer releases. Given there's still miscompilations getting fixed as late as 1.25.8, and 1.25 brought in large changesets for the new experimental GC, sticking it out while 1.24 is still getting patches a mere handful of weeks ago is not unreasonable.
What hacks are you relying on that makes it impossible to upgrade to 1.25 or even 1.26?
Does it even matter?
My solution for this is just use the current latest, or latest-1. There’s no reason not to. If your code is somehow stuck with an old version of Go, it should be considered a high priority bug, this is not normal.
I've seen this misconception so many times in open source projects - commits just bumping the version in go.mod to 'get the latest performance and security improvements.' Like no, that's not how it works, you just made your code compile with fewer compiler versions for no reason.
I think the directive could have been named better though, maybe something like min_version.
The transitive dependency case is what makes this painful in practice. You’re not even choosing that library it’s three levels deep in your dependency tree, and suddenly CI fails because some maintainer ran `go get go@latest` on a Saturday.
Unless I am mistaken or had some other fluke it will also just happily download the old version and build with that, even if there was a vulnerability, which has mostly led me to always bumping to the latest release when I touch it.
Someone n another thread mentioned the `toolchain` command, maybe I should look into this again.
Weird that this needs to be said. I’m not familiar with the Go ecosystem, but there is usually a natural incentive for library developers to reach more people, which means you’d want to support the oldest feasible version. If you don’t do that then someone will develop a better library which does support an older version. Is that not happening here?
What the article does not say is that if you don't have a recent enough version, by default, Go automatically downloads a more recent toolchain. So, for most users, this is transparent.
However, this behavior can be disabled (for example, when building for a Linux distribution).
> The version is the minimum version your project can be compiled with.
No, it's the minimum version my project is tested with.
> This means when you put a version like 1.25.7, you are deciding for everyone that imports you, transitively or directly, that they MUST be on Go 1.25.7+ to compile their project.
That is fine. This isn't Python or Java, you have no reason to ever be more than one version behind the current release. Just upgrade, it's painless.
> The fact that it defaults to the latest version is just a bad default that people should change.
Funny that: "cmd/go: change go mod init default go directive back to 1.N" https://github.com/golang/go/issues/77653
Thanks for the link! I could have sworn this was "fixed" and was surprised testing 1.26.1 showed the same (IMO bad) behavior! Didn't realize there was a revert. https://github.com/golang/go/issues/77923 looks like a hopeful path forward.
> The version is the minimum version your project can be compiled with.
Sure. But guess what, virtually nobody is going to find out what that "minimum version" is, and your blog post is not going to change that.
Just install the latest toolchain.
The issue I'm having with this is, that I'm using the newest version to test my library
Does go support automatic testing of all version from X..Y?
Otherwise I don't see it being usable to define another version than the one I'm testing with in my go.mod
>It is not the version you use to compile your project
But it is the version which they support. Pushing it back to an older version may result in bad behavior even if it does compile.
I think only languages which are still in beta have that kind of back compatibility. If a language breaks compatibility every two years (roughly Debian’s release schedule), it’s a toy, not a tool.
Go does not break compatibility every 2 years. I'm referring to Go fixing bugs in the language or standard runtime.
that is not a thing. it's not how compilers work.
Strictly speaking it does as miscompilations are a thing.
Furthermore the go version covers the stdlib so any bug there is resolved thus, and for obvious reasons those generally do not affect compilation.
I do not think this is a very compelling argument or likely to be an actual concern, but it is a thing.
I always stay up with the latest go releases and if I am touching one of my packages that are set to lower in go.mod, I update it. It is an easy maintenance task to make sure I am keeping up with the latest standard library and tooling changes and improvements.
Could there be a user dialog prompt about the suggested version and some control flow that allows people to manually override during installation as a happy medium between these approaches
> Its not your responsibility to ensure transitive importers of your library are on the latest version of Go. Don't make that decision for them.
and yet the Go maintainers did not include or build (in the future) a tool that determined the minimum version of Go that your application can be compiled in.
Same situation in Rust crates, AIUI.
In go, `go mod init` and `go get go@latest` (both recommended commands), both set a 'go <latest-version>' stanzas. In go, you _must_ set a minimum required version.
If you type 'cargo init', you will get 'edition = "2024"', but no 'rust-version'.
The situation is different because rust does not require a 'rust-version' in Cargo.toml, and in practice most crates do not have one, while in go it is required you specify a minimum version, there's no automation to set it to the true minimum, and most projects update it incorrectly in practice (because the go cli updates it incorrectly for you).
Oof, got it.
I think Rust is slightly different in practice even if they behave the same technically. I'm not sure Rust lets you even set the MSRV to a specific patch which is the biggest annoyance with Go; if they do it's so uncommon I've at least never seen it. And I don't believe any Rust tooling encourages you to set the MSRV to <latest Rust version> like tools in the Go ecosystem do.
Couldn't agree more.