Package name collision

Sometimes you need to import two packages that declare the same package name. A common example in Go is when both the crypto module and the math module provide packages named rand. This causes a name collision that you can resolve by assigning a local alias to one of the imports. Below is a concise, real-world example: we alias crypto/rand as crand so it doesn’t collide with math/rand. The example seeds a new math/rand.Rand using cryptographic randomness from crypto/rand.

Use a package alias when two imports share the same package name to avoid name collisions and make it clear which package you mean.

package main

import (
	"encoding/binary"
	crand "crypto/rand"
	"math/rand"
)

func seedRand() *rand.Rand {
	var b [8]byte

	_, err := crand.Read(b[:])
	if err != nil {
		panic("cannot seed with cryptographic random number generator")
	}

	seed := int64(binary.LittleEndian.Uint64(b[:]))
	r := rand.New(rand.NewSource(seed))
	return r
}

Explanation

crand "crypto/rand" gives the crypto/rand package the local name crand, preventing a collision with math/rand.
crand.Read fills an 8-byte array with cryptographically secure random bytes.
binary.LittleEndian.Uint64(b[:]) converts those bytes to a 64-bit unsigned integer; casting to int64 makes it suitable for rand.NewSource.
rand.New returns a *rand.Rand seeded with the secure value. Use this returned instance (r) to call pseudo-random functions like r.Intn(100).

Quick usage example

// Example showing how to use seedRand in practice
package main

import (
	"fmt"
)

func main() {
	r := seedRand()
	fmt.Println("Random int [0,100):", r.Intn(100))
}

When to use aliases (and naming tips)

Use an alias when two packages have the same base name (e.g., rand).
Prefer short, descriptive aliases that make intent obvious — e.g., crand for crypto/rand.
Avoid unnecessary aliases for a single import; they add cognitive overhead if the package name is already clear.

Summary table

Package imported	Recommended local name	When to alias
`crypto/rand`	`crand`	Collides with `math/rand` or to indicate cryptographic source
`math/rand`	`rand`	Default; use instance methods on `*rand.Rand` for reproducibility
`encoding/binary`	`binary`	Default; no alias needed unless colliding with a local symbol

Avoid overusing aliases — only introduce them when they resolve a real ambiguity or significantly improve readability. Poorly chosen aliases can make code harder to understand.

Links and references

Go packages: https://pkg.go.dev/std
crypto/rand: https://pkg.go.dev/crypto/rand
math/rand: https://pkg.go.dev/math/rand
encoding/binary: https://pkg.go.dev/encoding/binary
Effective Go — package names and conventions: https://go.dev/doc/effective_go

That’s it for this lesson.

Introduction

Introduction: Modules, Packages, and Imports

Core packages

API Development Project

CI/CD pipeline

Concurrency

Package name collision

Watch Video