A logo showing the text blog.marcnuri.com
Español
Home»Go»How to Initialize a New Go Project with Modules

Recent Posts

  • Fabric8 Kubernetes Client 7.2 is now available!
  • Connecting to an MCP Server from JavaScript using AI SDK
  • Connecting to an MCP Server from JavaScript using LangChain.js
  • The Future of Developer Tools: Adapting to Machine-Based Developers
  • Connecting to a Model Context Protocol (MCP) Server from Java using LangChain4j

Categories

  • Artificial Intelligence
  • Front-end
  • Go
  • Industry and business
  • Java
  • JavaScript
  • Legacy
  • Operations
  • Personal
  • Pet projects
  • Tools

Archives

  • May 2025
  • April 2025
  • March 2025
  • February 2025
  • January 2025
  • December 2024
  • November 2024
  • August 2024
  • June 2024
  • May 2024
  • April 2024
  • March 2024
  • February 2024
  • January 2024
  • December 2023
  • November 2023
  • October 2023
  • September 2023
  • August 2023
  • July 2023
  • June 2023
  • May 2023
  • April 2023
  • March 2023
  • February 2023
  • January 2023
  • December 2022
  • November 2022
  • October 2022
  • September 2022
  • August 2022
  • July 2022
  • June 2022
  • May 2022
  • March 2022
  • February 2022
  • January 2022
  • December 2021
  • November 2021
  • October 2021
  • September 2021
  • August 2021
  • July 2021
  • January 2021
  • December 2020
  • November 2020
  • October 2020
  • September 2020
  • August 2020
  • July 2020
  • June 2020
  • May 2020
  • February 2020
  • January 2020
  • December 2019
  • October 2019
  • September 2019
  • July 2019
  • March 2019
  • November 2018
  • July 2018
  • June 2018
  • May 2018
  • April 2018
  • March 2018
  • February 2018
  • December 2017
  • July 2017
  • January 2017
  • December 2015
  • November 2015
  • December 2014
  • March 2014
  • February 2011
  • November 2008
  • June 2008
  • May 2008
  • April 2008
  • January 2008
  • November 2007
  • September 2007
  • August 2007
  • July 2007
  • June 2007
  • May 2007
  • April 2007
  • March 2007

How to Initialize a New Go Project with Modules

2020-02-22 in Go tagged Dependency Management / Go by Marc Nuri | Last updated: 2025-02-11
Versión en Español

Introduction

Starting a new Go project is straightforward, thanks to Go's built-in tools and conventions. Since the introduction of Go modules in version 1.11, managing dependencies and organizing projects has become much easier.

Go modules allow you to define your project's dependencies, version them, and ensure reproducibility across different environments. This eliminates the need for older dependency management tools like GOPATH and provides a modern approach to project setup.

In this post, I'll show you how to initialize a new Go project, set up its basic structure, and follow best practices for organizing your code. Whether you're building a CLI tool, web server, or library, these steps will give you a solid foundation to get started.

Setting up the environment

Before starting, ensure that Go is installed on your system. You can download it from the official Go website.

After installation, verify it by running the following command:

bash
go version

This command should output the installed Go version, confirming it's correctly set up on your system.

Tip

If necessary, update your system PATH to include Go’s binary directories so that tools and installed binaries are available system-wide.

Creating a project directory

Create a new directory for your project and change into it. This isolates your project and keeps your work organized:

bash
mkdir my-new-go-project
cd my-new-go-project

Initializing a new Go module

To start a new Go project with modules, initialize your module with a unique name. You can do this by running the following command:

bash
go mod init github.com/your-username-or-organization/my-new-go-project
  • Replace github.com/your-username-or-organization/my-new-go-project with your desired module path.
  • This path should be unique to your project and follow the Go module naming conventions.
  • If you plan to publish your project as an open-source library, consider using a valid public repository URL.

This command creates a go.mod file in your project directory. The go.mod file contains your module's name and dependencies, ensuring your project is versioned and reproducible.

module github.com/your-username-or-organization/my-new-go-project

go 1.23

Creating your first Go application

Once you've initialized your module, you can start writing your Go application.

Create a new Go file in your project directory and add the following code:

main.go
package main

import "fmt"

func main() {
    fmt.Println("GREETINGS PROFESSOR FALKEN.")
}

This simple program prints a message to the console when executed. Notice that the package name is main, indicating this is an executable program.

Building and running your application

You can directly run your Go application without creating an executable by using the go run command:

bash
go run main.go

This command compiles and runs your application, displaying the output in your terminal.

To build your project into an executable binary, use the go build command:

bash
go build

This command compiles your application into an executable binary named after your project directory. You can run this binary directly from the command line:

bash
./my-new-go-project

Organizing your project

As your project grows, it's helpful to adopt a structured layout. A common structure might look like this:

my-new-go-project/
├── cmd/
│   └── your-app/
│       └── main.go
├── internal/
│   └── pkg/
│       └── your_private_package/
├── pkg/
│   └── your_public_package/
├── go.mod
├── go.sum
└── README.md
Directory / FileDescription
cmd/

Contains the main applications for your project.
Each application should have its own directory matching the executable name you want.

internal/Contains private application and library code that should not be imported by other projects.
pkg/Contains library code that can be imported by other projects.
go.modDefines your project's module path and dependencies.
go.sumContains the expected cryptographic checksums of the content of specific module versions.

This structure promotes maintainability and scalability.

Tip

For smaller projects, you can keep everything in the root directory with a single main.go file.

Managing dependencies

Go modules make it easy to manage dependencies. When you import a package in your code, Go automatically downloads and caches the required dependencies.

To add a new dependency to your project, use the go get command:

bash
go get github.com/username-or-organization/dependency

For example, to add gin-gonic to your project, run the following command:

bash
go get github.com/gin-gonic/gin

This command downloads the gin package and adds it to your go.mod file as a dependency.

After adding a new dependency, run the following command:

bash
go mod tidy

This command ensures that your go.mod and go.sum files are up to date by adding missing requirements and removing any unnecessary dependencies.

Conclusion

Starting a new Go project is simple and efficient with its modular approach and built-in tools. By following these steps, you’ll have a solid foundation for any application, whether it's a CLI tool, web server, or library.

Experiment with these techniques and adapt the structure to suit your project’s needs. Feel free to share this guide with others getting started with Go!

Twitter iconFacebook iconLinkedIn iconPinterest iconEmail icon

Post navigation
Kubernetes Client for Java: Introducing YAKCUnderstanding Variadic Functions in Go
© 2007 - 2025 Marc Nuri