How to Migrate Existing Code to Use the Standard uuid Package in Go

Migrate to the standard library uuid package by updating your go.mod to Go 1.27, replacing third-party imports like github.com/google/uuid with "uuid", and refactoring API calls from googleuuid.New() to uuid.New() before running go mod tidy to remove legacy dependencies.

The JetBrains/go-modern-guidelines repository defines the stdlib_uuid guideline that instructs developers to prefer the standard-library uuid package over third-party implementations when targeting Go 1.27 or newer. This migration reduces external dependencies and binary size while aligning with modern Go best practices.

Verify Your Go Version Requirement

The standard uuid package was introduced in Go 1.27. Before you migrate existing code to use the standard uuid package, ensure your module declares the correct version in go.mod.

// go.mod
go 1.27

If your project uses an older version, upgrade your toolchain and update the go directive accordingly. The guideline definition in internal/guidelines/guidelines.json (lines 40-60) explicitly activates only for Go 1.27+ targets.

Locate Third-Party UUID Imports

Search your codebase for common third-party UUID implementations that the guideline recommends replacing. The standard migration targets packages such as github.com/google/uuid and github.com/gofrs/uuid.

Use grep or your IDE to find legacy imports:

grep -r "github.com/google/uuid" .
grep -r "github.com/gofrs/uuid" .

Replace Import Statements

Update all import declarations to use the standard library path. The transformation removes the external module identifier and uses the bare import path "uuid".

Before:

import googleuuid "github.com/google/uuid"

After:

import "uuid"

As implemented in the JetBrains/go-modern-guidelines source, this import swap is the foundational step of the stdlib_uuid guideline.

Update API Calls

Most third-party libraries expose compatible APIs with New, Parse, and String methods. After changing imports, update your function calls to use the standard package name directly.

UUID Generation

Before:

id := googleuuid.New()
text := id.String()

After:

id := uuid.New()
text := id.String()

UUID Parsing

Before:

id, err := googleuuid.Parse(raw)
if err != nil { 
    return err 
}

After:

id, err := uuid.Parse(raw)
if err != nil { 
    return err 
}

The test suite in internal/guidelines/guidelines_test.go (lines 33-45) validates that these transformations activate correctly when the target version is Go 1.27 or newer.

Validate and Clean Up Dependencies

After updating imports and API calls, verify the migration with compiler checks and remove the obsolete dependency.

1. Run go vet to catch any remaining references to the old package.
2. Execute go test to ensure no type mismatches or missing helper functions break your build.
3. Run go mod tidy to strip the third-party UUID library from go.mod and go.sum.

Following these steps completes the migration, eliminating external dependencies while maintaining identical functionality.

Summary

• The stdlib_uuid guideline requires Go 1.27 or newer as defined in internal/guidelines/guidelines.json.
• Replace imports of github.com/google/uuid or github.com/gofrs/uuid with the standard "uuid" path.
• Update API calls from googleuuid.New() to uuid.New() and similarly for Parse().
• Validate changes with go vet and go test, then clean up with go mod tidy.
• Reference the transformation examples in internal/guidelines/guidelines.json#L40-L60 for exact syntax patterns.

Frequently Asked Questions

Which Go version introduced the standard uuid package?

The standard library uuid package became available in Go 1.27. The guideline definition in internal/guidelines/guidelines.json specifically targets this version and newer, as verified by the test logic in internal/guidelines/guidelines_test.go#L33-L45.

Can I use the standard uuid package alongside third-party libraries temporarily?

While technically possible during incremental migration, the stdlib_uuid guideline recommends complete replacement to avoid duplicate logic and reduce binary size. Mixing packages requires aliasing imports, which increases technical debt rather than resolving it.

Are the API signatures identical between google/uuid and the standard library?

The core methods New(), Parse(), and String() maintain compatible signatures between github.com/google/uuid and the standard uuid package. However, verify any specialized utility functions separately, as the standard library implements a focused API that may not include niche helpers from third-party alternatives.

How do I verify the migration worked correctly?

Run go vet to detect lingering references to third-party packages, then execute your test suite with go test. Finally, use go mod tidy and confirm the external dependency no longer appears in your go.mod file, ensuring you have successfully migrated to the standard library implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}