This post will be a rundown of all the Go runtime environment variables, what they mean, and what they are used for.
The following variables are available in the latest release of Go, which at the time of writing is 1.13.
GOGC refers to a target percentage at which to run the garbage collector relative to the amount of data left from the
latest run. For example, a
GOGC variable set to 100 (the default) means that the garbage collector will run when the
heap roughly doubles in size. In other words, a higher percentage means garbage will be collected
less often, and a lower percentage means it will collect garbage more often. If you set the variable to
garbage collection will be turned off entirely.
GOMAXPROCS controls the number of OS threads that can used to execute Go simultaneously. It defaults to the number
of CPUs available to the program at runtime.
GORACE sets the options for the Go race detector and should be in
key=value format, with multiple pairs separated
by a single space. The options are:
- log_path: The race detector will write a report to stdout be default. This can also be set to either stderr or a path. If a path is specified, it will write the report to a file named log_path.pid at the path specifed.
- exitcode: The status code to use when exiting after a detected race. The default is 66.
- strip_path_prefix: This strips the given prefix from reported file paths. The default prefix is the empty string "".
- history_size: The per-goroutine memory access history is 32K * 2**history_size elements. Increasing this value can avoid a “failed to restore the stack” error in reports, at the cost of increased memory usage. The default is 1.
- halt_on_error: Controls whether the program exits after the first data race is detected. The default is 0.
GOTRACEBACK will control the amount of log information given when a Go program fails. The available options are:
- single (the default): Prints a stack trace of the current goroutine, if available. Otherwise, it will give a stacktrace of all goroutines.
- none: Omits goroutine stack traces.
- all: Adds all user-defined goroutine stack traces.
- system: Similar to all but it also includes stack traces for internal goroutines as well as frames for runtime functions.
- crash: Similar to system but it will also force a seg fault or access violation, if permitted by the operating system. This is useful for debugging when you want a “snapshot” of the RAM at the time the program panics.
GOOS variables are used when building a Go program.
GOARCH is the target architecture and
the target operating system. Valid combintations are as follows:
1$GOOS $GOARCH2aix ppc643android 3864android amd645android arm6android arm647darwin 3868darwin amd649darwin arm10darwin arm6411dragonfly amd6412freebsd 38613freebsd amd6414freebsd arm15illumos amd6416js wasm17linux 38618linux amd6419linux arm20linux arm6421linux ppc6422linux ppc64le23linux mips24linux mipsle25linux mips6426linux mips64le27linux s390x28netbsd 38629netbsd amd6430netbsd arm31openbsd 38632openbsd amd6433openbsd arm34openbsd arm6435plan9 38636plan9 amd6437plan9 arm38solaris amd6439windows 38640windows amd64
This is useful when you are compiling your Go programs for other operating systems. For example, if I wanted a package to target macOS amd64 machines I could run
1GOOS=darmin GOARCH=amd64 go build packageName
GOPATH specifies the location of your workspace. It defaults to a directory named
go inside your home directory.
This is separate from the install location of Go. Typically, a workspace is comprised of two directories at its root,
src, which contains Go source files, and
bin, which contains compiled Go executables. Binaries are downloaded into
GOROOT variable points to the installation of Go and should not be set by the user as it is already
embedded in the go toolchain.
GODEBUG variable controls debugging variables within the runtime. It is defined using
and has many, many options so I decided to quote the Go docs on this one:
From https://golang.org/pkg/runtime/ the options are:
1allocfreetrace: setting allocfreetrace=1 causes every allocation to be2profiled and a stack trace printed on each object's allocation and free.34clobberfree: setting clobberfree=1 causes the garbage collector to5clobber the memory content of an object with bad content when it frees6the object.78cgocheck: setting cgocheck=0 disables all checks for packages9using cgo to incorrectly pass Go pointers to non-Go code.10Setting cgocheck=1 (the default) enables relatively cheap11checks that may miss some errors. Setting cgocheck=2 enables12expensive checks that should not miss any errors, but will13cause your program to run slower.1415efence: setting efence=1 causes the allocator to run in a mode16where each object is allocated on a unique page and addresses are17never recycled.1819gccheckmark: setting gccheckmark=1 enables verification of the20garbage collector's concurrent mark phase by performing a21second mark pass while the world is stopped. If the second22pass finds a reachable object that was not found by concurrent23mark, the garbage collector will panic.2425gcpacertrace: setting gcpacertrace=1 causes the garbage collector to26print information about the internal state of the concurrent pacer.2728gcshrinkstackoff: setting gcshrinkstackoff=1 disables moving goroutines29onto smaller stacks. In this mode, a goroutine's stack can only grow.3031gcstoptheworld: setting gcstoptheworld=1 disables concurrent garbage collection,32making every garbage collection a stop-the-world event. Setting gcstoptheworld=233also disables concurrent sweeping after the garbage collection finishes.3435gctrace: setting gctrace=1 causes the garbage collector to emit a single line to standard36error at each collection, summarizing the amount of memory collected and the37length of the pause. The format of this line is subject to change.38Currently, it is:39 gc # @#s #%: #+#+# ms clock, #+#/#/#+# ms cpu, #->#-># MB, # MB goal, # P40where the fields are as follows:41 gc # the GC number, incremented at each GC42 @#s time in seconds since program start43 #% percentage of time spent in GC since program start44 #+...+# wall-clock/CPU times for the phases of the GC45 #->#-># MB heap size at GC start, at GC end, and live heap46 # MB goal goal heap size47 # P number of processors used48The phases are stop-the-world (STW) sweep termination, concurrent49mark and scan, and STW mark termination. The CPU times50for mark/scan are broken down in to assist time (GC performed in51line with allocation), background GC time, and idle GC time.52If the line ends with "(forced)", this GC was forced by a53runtime.GC() call.5455Setting gctrace to any value > 0 also causes the garbage collector56to emit a summary when memory is released back to the system.57This process of returning memory to the system is called scavenging.58The format of this summary is subject to change.59Currently it is:60 scvg#: # MB released printed only if non-zero61 scvg#: inuse: # idle: # sys: # released: # consumed: # (MB)62where the fields are as follows:63 scvg# the scavenge cycle number, incremented at each scavenge64 inuse: # MB used or partially used spans65 idle: # MB spans pending scavenging66 sys: # MB mapped from the system67 released: # MB released to the system68 consumed: # MB allocated from the system6970madvdontneed: setting madvdontneed=1 will use MADV_DONTNEED71instead of MADV_FREE on Linux when returning memory to the72kernel. This is less efficient, but causes RSS numbers to drop73more quickly.7475memprofilerate: setting memprofilerate=X will update the value of runtime.MemProfileRate.76When set to 0 memory profiling is disabled. Refer to the description of77MemProfileRate for the default value.7879invalidptr: defaults to invalidptr=1, causing the garbage collector and stack80copier to crash the program if an invalid pointer value (for example, 1)81is found in a pointer-typed location. Setting invalidptr=0 disables this check.82This should only be used as a temporary workaround to diagnose buggy code.83The real fix is to not store integers in pointer-typed locations.8485sbrk: setting sbrk=1 replaces the memory allocator and garbage collector86with a trivial allocator that obtains memory from the operating system and87never reclaims any memory.8889scavenge: scavenge=1 enables debugging mode of heap scavenger.9091scheddetail: setting schedtrace=X and scheddetail=1 causes the scheduler to emit92detailed multiline info every X milliseconds, describing state of the scheduler,93processors, threads and goroutines.9495schedtrace: setting schedtrace=X causes the scheduler to emit a single line to standard96error every X milliseconds, summarizing the scheduler state.9798tracebackancestors: setting tracebackancestors=N extends tracebacks with the stacks at99which goroutines were created, where N limits the number of ancestor goroutines to100report. This also extends the information returned by runtime.Stack. Ancestor's goroutine101IDs will refer to the ID of the goroutine at the time of creation; it's possible for this102ID to be reused for another goroutine. Setting N to 0 will report no ancestry information.
Finally, here is a quick list of other general environemnt variables gathered from the Go docs:
- GCCGO: The gccgo command to run for ‘go build -compiler=gccgo’.
- GOBIN: The directory where ‘go install’ will install a command.
- GOCACHE: The directory where the go command will store cached information for reuse in future builds.
- GOENV: The location of the Go environment configuration file. Cannot be set using ‘go env -w’.
- GOFLAGS: A space-separated list of -flag=value settings to apply to go commands by default, when the given flag is known by the current command. Each entry must be a standalone flag. Because the entries are space-separated, flag values must not contain spaces. Flags listed on the command line are applied after this list and therefore override it.
- GOPROXY: URL of Go module proxy.
- GOPRIVATE, GONOPROXY, GONOSUMDB: Comma-separated list of glob patterns (in the syntax of Go’s path.Match) of module path prefixes that should always be fetched directly or that should not be compared against the checksum database.
- GOSUMDB: The name of checksum database to use and optionally its public key and URL.
- GOTMPDIR: The directory where the go command will write temporary source files, packages, and binaries.
Hopefully this is helpful to those who were curious about all the variables available to the Go runtime. If you are interested in learning more, I recommend heading over to the Go docs for more information.