By Gopher Guides and Manikandan Kurup So far in our How To Code in Go series, you have used the command go run to automatically compile your source code and run the resulting executable. Although this command is useful for testing your code on the command line, distributing or deploying your application requires you to build your code into a shareable binary executable, or a single file containing machine code that can run your application. To do this, you can use the Go toolchain to build and install your program. In Go, the process of translating source code into a binary executable is called building. Once this executable is built, it will contain not only your application, but also all the support code needed to execute the binary on the target platform. This means that a Go binary does not need system dependencies such as Go tooling to run on a new system. Installing a program makes it easier to run the executable from anywhere on your system by placing it in a directory included in your system’s $PATH. In this tutorial, you will use the Go toolchain to run, build, and install a sample Hello, World! program, allowing you to use, distribute, and deploy future applications effectively. You will also work with Go modules, which play a central role in how modern Go programs are built and managed. To follow the example in this article, you will need: First, create an application to use as an example for demonstrating the Go toolchain. To do this, you will use the classic “Hello, World!” program from the How To Write Your First Program in Go tutorial. Create a directory called greeter: Next, move into the newly created directory and create the main.go file in the text editor of your choice: Once the file is open, add the following contents: When run, this program will print the phrase Hello, World! to the console and then exit successfully. Save and exit the file. To test the program, use the go run command, as you’ve done in previous tutorials: You’ll receive the following output: As mentioned before, the go run command compiles your source file into a temporary executable binary and then runs the compiled program. However, this tutorial aims to build the binary in such a way that you can share and distribute it at will. To do this, you will use the go build command in the next step. Go programs and libraries are built around the core concept of a module. A module defines your project and contains information about the libraries your program depends on, along with their versions. To initialize your project as a Go module, run the following command in your greeter directory: This will create a go.mod file, which declares the module name and the version of Go used for the project: The go.mod file is used by the Go toolchain to resolve and manage dependencies when building your program. When you run commands like go build or go install, Go will automatically download any required modules and store them in the module cache on your system. Go may prompt you to run go mod tidy to add or clean up dependency requirements. This command ensures that your go.mod and go.sum files accurately reflect the dependencies used in your code. For this example, no external dependencies are used, so running go mod tidy will not make any changes. Using go build, you can generate an executable binary for your sample Go application, allowing you to distribute and deploy the program where you want. Try this with main.go. In your greeter directory, run the following command: If you do not provide an argument to this command, go build will compile the main package in your current directory, including all *.go files. It will also include all required dependencies defined in your module. The resulting binary contains everything needed to execute the program on a system with the same operating system and architecture. In this case, you built your greeter application into an executable file that was added to your current directory. Check this by running the ls command: If you are running macOS or Linux, you will find a new executable file that has been named after the directory in which you built your program: Note: On Windows, your executable will be greeter.exe. By default, go build generates an executable for the current platform and architecture. For example, if built on a linux/amd64 system, the executable will be compatible with other linux/amd64 systems, even if Go is not installed. Go also supports building binaries for different platforms and architectures, which you can explore further in our Building Go Applications for Different Operating Systems and Architectures article. Now that you’ve created your executable, run it to make sure the binary has been built correctly. On macOS or Linux, run the following command: The output of the binary will match the output from when you ran the program with go run: Now you have created a single executable binary that contains not only your program, but also all of the code needed to run it. You can now distribute this program to new systems or deploy it to a server, as long as the target system matches the operating system and architecture used to build the binary. By default, the go build command creates a binary for your current operating system and architecture. However, Go also supports cross-compilation, allowing you to build binaries for different platforms without needing access to those systems. You can specify the target platform by setting the GOOS (operating system) and GOARCH (architecture) environment variables when running go build. For example, to build a Linux binary on macOS or Windows, run: To build a Windows executable: These commands produce binaries that can run on the specified target platform, as long as the operating system and architecture match. Some common combinations include: Cross-compilation is particularly useful when preparing applications for deployment, distributing prebuilt binaries, or building software in CI/CD pipelines. For a more detailed list of supported platforms and architectures, refer to the Building Go Applications for Different Operating Systems and Architectures article. In the next section, this tutorial will explain how a binary is named and how you can customize it to have better control over the build process of your program. Now that you know how to generate an executable, the next step is understanding how Go chooses a name for the binary and how to customize it for your project. When you run go build, Go assigns a default name to the generated executable based on the name of the directory containing your main package. Since your project directory is named greeter, the resulting binary is also named greeter. In more complex programs that require specific naming conventions, these default values will not always be the best choice for naming your binary. In these cases, you can customize the output using the -o flag. To test this out, build a new executable named hello and place it in a subfolder called bin. You don’t have to create this folder; Go will create it during the build process if it does not already exist. Run the following go build command with the -o flag: The -o flag tells Go to write the output binary to the specified file path. In this case, the result is a new executable named hello in a subfolder named bin. To test the new executable, change into the new directory and run the binary: You will receive the following output: You can now customize the name and location of your executable to fit the needs of your project. However, with go build, you are still limited to running your binary from its location unless that directory is included in your system’s $PATH. To use newly built executables from anywhere on your system, you can install them using go install. So far in this article, you have generated executable binaries from your .go source files. These executables are useful for distributing, deploying, and testing your programs, but they are typically run from their current location unless that directory is included in your system’s $PATH. To make programs easier to use, you can install them and run them from anywhere on your system. To understand what this means, you will use the go install command to install your sample application. The go install command behaves similarly to go build, but instead of placing the executable in the current directory (or a directory specified with -o), it installs the binary into a directory intended for executable programs. By default, this is $GOBIN if it is set, or $GOPATH/bin otherwise. To find your $GOPATH, run the following command: The output you receive will vary, but the default is a go directory inside your $HOME directory: Since installed binaries are placed in $GOBIN or $GOPATH/bin, this directory must be included in your $PATH environment variable. With this directory set up, move back to your greeter directory: Now run the install command: This will build your binary and install it into your executable directory. To verify this, run: You should see your binary listed: Note: The go install command does not support the -o flag. It installs binaries using their default name. With the binary installed, test that the program can be run from outside its source directory. Move to your home directory: This will yield the following: In addition to installing local programs, go install can also be used to install binaries from remote modules by specifying a version. For example: This will download, build, and install the specified tool without requiring you to clone the repository manually. The Go toolchain provides three commonly used commands for working with programs: go run, go build, and go install. While they may appear similar, each serves a different purpose in the development workflow. The following table summarizes their key differences: When you run go run, Go creates a temporary binary behind the scenes and immediately executes it. This is useful during development, but the binary is not saved for reuse. The go build command generates a reusable executable file in your current directory. This is the most common way to prepare a program for distribution or deployment. The go install command builds the binary and places it in a directory on your system’s $PATH, allowing you to run the program from any location. This is especially useful for command-line tools and reusable utilities. In general, use go run for development, go build for producing binaries, and go install when you want to make a program available system-wide. When working with the Go toolchain, you may encounter errors related to your environment, module configuration, or executable paths. These issues are often caused by misconfigured system variables, incomplete installations, or dependency conflicts. The following sections outline common issues, explain why they occur, and walk through how to resolve them. If your system reports that the go command is not found, it typically means one of two things: Go is not installed on your system, or the directory containing the Go binary is not included in your shell’s $PATH variable. To verify whether Go is installed and accessible, run: If this command succeeds, it will print the installed version of Go, such as go version go1.26.1 linux/amd64. If it fails with a “command not found” error, you will need to either install Go or update your $PATH. On most Linux systems, Go is installed to /usr/local/go. You can add the Go binary directory to your $PATH by adding the following line to your shell configuration file (such as ~/.bashrc or ~/.zshrc): After saving the file, apply the changes by sourcing it: If Go is not installed at all, follow the How To Install Go on Ubuntu guide to set it up from scratch. If you run go install successfully but receive a “command not found” error when trying to execute your program, the most likely cause is that the directory where Go installs binaries is not included in your system’s $PATH. By default, go install places binaries in the directory specified by the $GOBIN environment variable. If $GOBIN is not set, Go falls back to $GOPATH/bin. First, check whether $GOBIN is set: If this returns an empty result, Go is using the default location. Check where that is by running: This will return a path like $HOME/go. In that case, your installed binaries are located in $HOME/go/bin. To make installed binaries accessible from anywhere, add the appropriate directory to your $PATH. Open your shell configuration file and add: Then reload your shell configuration: After this, you should be able to run your installed Go programs by name from any directory. Errors such as missing go.sum entry or no required module provides package can occur when your module files (go.mod and go.sum) are out of sync with the packages your code actually imports. This is common after adding or removing dependencies, switching branches, or pulling changes from a shared repository. To resolve this, run: This command scans your source code, adds any missing dependencies to go.mod, downloads them, and updates the go.sum file with the expected cryptographic checksums. It also removes any dependencies that are no longer referenced in your code. If you continue to see module errors after running go mod tidy, verify that your go.mod file lists the correct module path and Go version at the top of the file. You can open it with: The output should include a module directive matching your project name and a go directive specifying the Go version, such as: If go build fails with errors related to downloading or resolving dependencies, the issue may stem from several possible causes: To clear the module cache and force Go to re-download all dependencies, run: Then rebuild your project: This will download fresh copies of all required modules and attempt the build again. If your binary builds successfully but does not behave as expected when you run it, there are several things to check: This will output details such as ELF 64-bit LSB executable (for Linux) or Mach-O 64-bit executable arm64 (for macOS on Apple Silicon). If the platform does not match your system, rebuild the binary with the correct GOOS and GOARCH values. By systematically checking these areas, you can identify and resolve most common issues encountered when building and installing Go programs. Go provides several commands for building and running programs directly from the command line, each suited to a different stage of the development workflow. The simplest way to run a program is with go run main.go, which compiles your source code into a temporary binary behind the scenes and immediately executes it. This is ideal for quick testing during development because you don’t have to manually manage any output files; Go handles everything automatically and discards the binary after the program finishes. When you’re ready to produce a permanent, distributable executable, use go build. Running go build in the directory containing your main package compiles all .go files and their dependencies into a single binary, which is placed in your current working directory. The binary is named after the enclosing directory by default. For example, a project in a folder called greeter produces a binary named greeter. You can then run the binary directly with ./greeter on Linux or macOS, or greeter.exe on Windows. If you want to customize the output name or location, use the -o flag, such as go build -o bin/myapp. For programs you want to run from anywhere on your system, use go install, which builds the binary and places it in a directory on your system’s $PATH (typically $GOPATH/bin), making it globally accessible without specifying the full file path. Both go build and go install compile your Go source code into an executable binary, but they serve different purposes and place the resulting binary in different locations. go build compiles your program and writes the output binary to your current working directory by default. You can also specify a custom output path using the -o flag, such as go build -o bin/hello. This makes go build well-suited for local development, testing, and preparing binaries for distribution or deployment to other systems. The binary stays wherever you put it, and you run it by providing the path explicitly (for example, ./bin/hello). go install, on the other hand, compiles the program and places the binary in a centralized directory intended for executable programs, specifically $GOBIN if that environment variable is set, or $GOPATH/bin otherwise. Because this directory is typically included in your system’s $PATH, any program installed with go install can be run by name from any location on your system, just like any other system command. However, go install does not support the -o flag, so you cannot customize the binary’s name or destination. In short, use go build when you need control over where the binary goes (such as when packaging for deployment), and use go install when you want to make a tool or utility available system-wide for everyday use. The go get command has changed over time, and its behavior depends on how you use it. In recent versions of Go, go get should not be used to install executable binaries; instead, use go install <module>@<version> to download, build, and install a tool. Today, go get serves a narrower purpose: it is used exclusively to add, update, or remove module dependencies in your project’s go.mod file. For example, running go get golang.org/x/text@latest updates your module’s dependency on that package to the latest version, but it does not build or install anything. To download, build, and install an executable binary from a remote module, you should use go install with an explicit version suffix. For example, go install golang.org/x/tools/cmd/goimports@latest fetches the goimports tool, builds it, and places the binary in your $GOBIN or $GOPATH/bin directory. This separation of responsibilities (go get for dependency management and go install for binary installation) makes the toolchain’s behavior clearer and more predictable. Installing Go on Linux involves downloading the official binary distribution, extracting it to the appropriate system directory, and configuring your shell environment so the go command is accessible from the terminal. Start by visiting the official Go downloads page and downloading the latest Linux binary archive (typically a .tar.gz file for the amd64 architecture). Once downloaded, extract the archive to /usr/local, which is the standard installation location for Go on Linux systems: This creates the directory /usr/local/go, which contains the Go toolchain. Next, you need to add Go’s bin directory to your system’s $PATH so that your shell can find the go command. Open your shell configuration file (such as ~/.bashrc, ~/.zshrc, or ~/.profile) and add the following line: After saving the file, apply the changes by running source ~/.bashrc (or the equivalent command for your shell). You should also set up a Go workspace directory and add $GOPATH/bin to your $PATH so that binaries installed with go install are accessible system-wide. To verify that Go is installed correctly, run go version. This should print the installed Go version, confirming that the installation was successful. For a detailed, step-by-step walkthrough, refer to the How To Install Go on Ubuntu guide. $GOBIN is an environment variable that specifies the directory where go install places compiled executable binaries. When $GOBIN is not set (which is the default), Go falls back to placing binaries in $GOPATH/bin. Setting $GOBIN explicitly gives you fine-grained control over where your installed tools and programs end up, which can be useful if you want to keep Go binaries separate from other files in your Go workspace. To configure $GOBIN, add an export statement to your shell configuration file. For example, if you want installed binaries to go to ~/go-tools/bin, add the following to your ~/.bashrc or ~/.zshrc: After saving the file, apply the changes by running source ~/.bashrc. It is important to also ensure that the directory you set as $GOBIN is included in your $PATH, so that installed programs can be run by name from any location: You can verify the currently configured value at any time by running go env GOBIN. If the output is empty, it means $GOBIN is not set and Go is using the default $GOPATH/bin directory. Any change to $GOBIN takes effect for all subsequent go install commands; previously installed binaries are not moved automatically and will remain in their original location. One of Go’s most powerful features is its built-in support for cross-compilation, which allows you to build executable binaries for a different operating system or CPU architecture directly from your development machine without needing to install any additional compilers, toolchains, or virtual machines. Cross-compilation is controlled by two environment variables: GOOS, which specifies the target operating system, and GOARCH, which specifies the target CPU architecture. You set these variables before running go build, and Go produces a binary compatible with the specified platform. For example, to build a Linux binary while working on macOS, you would run: Similarly, to produce a Windows executable from a Linux or macOS machine: Some of the most commonly used platform and architecture combinations include linux/amd64 for standard 64-bit Linux servers, windows/amd64 for 64-bit Windows systems, darwin/amd64 for Intel-based Macs, and darwin/arm64 for Apple Silicon Macs. You can view the full list of supported platforms by running go tool dist list. Cross-compilation is especially valuable in CI/CD pipelines, where you may need to produce binaries for multiple target platforms from a single build environment. It is also useful when developing on macOS but deploying to Linux servers, or when distributing prebuilt binaries to users on different operating systems. Because Go statically links its binaries by default, the resulting executables have no external dependencies and can run on the target system without any additional setup. When go install completes successfully but you receive a “command not found” error when trying to run the installed program, the issue is almost always related to your system’s $PATH configuration. The binary was built and placed in the correct directory, but your shell doesn’t know to look in that directory when you type a command. By default, go install places binaries in the directory specified by the $GOBIN environment variable. If $GOBIN is not set, Go falls back to $GOPATH/bin (which is typically $HOME/go/bin). You can confirm exactly where your binary was installed by running go env GOBIN and go env GOPATH to check both values. Once you know the installation directory, verify that it is included in your $PATH by running echo $PATH and looking for the relevant path in the output. If the directory is missing, add it to your shell configuration file (~/.bashrc, ~/.zshrc, or ~/.profile) with the following line: Then apply the change by running source ~/.bashrc (or the equivalent for your shell). After this, your installed Go binaries should be accessible by name from any directory. Note that if you set a custom $GOBIN, you should add that specific directory to your $PATH instead of $GOPATH/bin. If you have multiple terminal sessions open, you will need to reload the configuration in each one or open new terminal windows for the change to take effect. In this tutorial, you demonstrated how the Go toolchain makes it easy to run, build, and install executable binaries from source code. These binaries can be distributed to run on other systems, even those that do not have Go installed. You also used go install to build and install your programs as executables in your system’s $PATH, making them accessible from anywhere. You also worked with Go modules, which manage dependencies and ensure that your builds are consistent and reproducible. Together, these tools form the foundation of how Go applications are developed and distributed. Now that you know the basics of go run, go build, and go install, you can explore how to make modular source code with the Customizing Go Binaries with Build Tags tutorial, or how to build for different platforms with Building Go Applications for Different Operating Systems and Architectures. If you’d like to learn more about the Go programming language in general, check out the entire How To Code in Go series. Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases. Learn more about our products Go (or GoLang) is a modern programming language originally developed by Google that uses high-level syntax similar to scripting languages. It is popular for its minimal syntax and innovative handling of concurrency, as well as for the tools it provides for building native binaries on foreign platforms. Browse Series: 53 tutorials Gopher Guides is a training and consulting company specializing in Go and Go related technologies. Co-founder:s Mark Bates & Cory LaNou. With over 6 years of experience in tech publishing, Mani has edited and published more than 75 books covering a wide range of data science topics. Known for his strong attention to detail and technical knowledge, Mani specializes in creating clear, concise, and easy-to-understand content tailored for developers. This textbox defaults to using Markdown to format your answer. You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link! Please complete your information! Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation. Full documentation for every DigitalOcean product. The Wave has everything you need to know about building a business, from raising funding to marketing your product. Stay up to date by signing up for DigitalOcean’s Infrastructure as a Newsletter. New accounts only. By submitting your email you agree to our Privacy Policy Scale up as you grow — whether you're running one virtual machine or ten thousand. From GPU-powered inference and Kubernetes to managed databases and storage, get everything you need to build, scale, and deploy intelligent applications.