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

> Easily migrate your Go code to the standard uuid package. Update imports, refactor calls, and tidy dependencies for a cleaner, more efficient solution.

- Repository: [JetBrains/go-modern-guidelines](https://github.com/jetbrains/go-modern-guidelines)
- Tags: migration-guide
- Published: 2026-08-30

---

**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`.

```text
// 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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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:

```bash
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:

```go
import googleuuid "github.com/google/uuid"

```

After:

```go
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:

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

```

After:

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

```

### UUID Parsing

Before:

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

```

After:

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

```

The test suite in [`internal/guidelines/guidelines_test.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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.