1# UUID
2
3[](https://github.com/gofrs/uuid/blob/master/LICENSE)
4[](https://travis-ci.org/gofrs/uuid)
5[](http://godoc.org/github.com/gofrs/uuid)
6[](https://codecov.io/gh/gofrs/uuid/)
7[](https://goreportcard.com/report/github.com/gofrs/uuid)
8
9Package uuid provides a pure Go implementation of Universally Unique Identifiers
10(UUID) variant as defined in RFC-4122. This package supports both the creation
11and parsing of UUIDs in different formats.
12
13This package supports the following UUID versions:
14* Version 1, based on timestamp and MAC address (RFC-4122)
15* Version 3, based on MD5 hashing of a named value (RFC-4122)
16* Version 4, based on random numbers (RFC-4122)
17* Version 5, based on SHA-1 hashing of a named value (RFC-4122)
18
19This package also supports experimental Universally Unique Identifier implementations based on a
20[draft RFC](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-03) that updates RFC-4122
21* Version 6, a k-sortable id based on timestamp, and field-compatible with v1 (draft-peabody-dispatch-new-uuid-format, RFC-4122)
22* Version 7, a k-sortable id based on timestamp (draft-peabody-dispatch-new-uuid-format, RFC-4122)
23
24The v6 and v7 IDs are **not** considered a part of the stable API, and may be subject to behavior or API changes as part of minor releases
25to this package. They will be updated as the draft RFC changes, and will become stable if and when the draft RFC is accepted.
26
27## Project History
28
29This project was originally forked from the
30[github.com/satori/go.uuid](https://github.com/satori/go.uuid) repository after
31it appeared to be no longer maintained, while exhibiting [critical
32flaws](https://github.com/satori/go.uuid/issues/73). We have decided to take
33over this project to ensure it receives regular maintenance for the benefit of
34the larger Go community.
35
36We'd like to thank Maxim Bublis for his hard work on the original iteration of
37the package.
38
39## License
40
41This source code of this package is released under the MIT License. Please see
42the [LICENSE](https://github.com/gofrs/uuid/blob/master/LICENSE) for the full
43content of the license.
44
45## Recommended Package Version
46
47We recommend using v2.0.0+ of this package, as versions prior to 2.0.0 were
48created before our fork of the original package and have some known
49deficiencies.
50
51## Installation
52
53It is recommended to use a package manager like `dep` that understands tagged
54releases of a package, as well as semantic versioning.
55
56If you are unable to make use of a dependency manager with your project, you can
57use the `go get` command to download it directly:
58
59```Shell
60$ go get github.com/gofrs/uuid
61```
62
63## Requirements
64
65Due to subtests not being supported in older versions of Go, this package is
66only regularly tested against Go 1.7+. This package may work perfectly fine with
67Go 1.2+, but support for these older versions is not actively maintained.
68
69## Go 1.11 Modules
70
71As of v3.2.0, this repository no longer adopts Go modules, and v3.2.0 no longer has a `go.mod` file. As a result, v3.2.0 also drops support for the `github.com/gofrs/uuid/v3` import path. Only module-based consumers are impacted. With the v3.2.0 release, _all_ gofrs/uuid consumers should use the `github.com/gofrs/uuid` import path.
72
73An existing module-based consumer will continue to be able to build using the `github.com/gofrs/uuid/v3` import path using any valid consumer `go.mod` that worked prior to the publishing of v3.2.0, but any module-based consumer should start using the `github.com/gofrs/uuid` import path when possible and _must_ use the `github.com/gofrs/uuid` import path prior to upgrading to v3.2.0.
74
75Please refer to [Issue #61](https://github.com/gofrs/uuid/issues/61) and [Issue #66](https://github.com/gofrs/uuid/issues/66) for more details.
76
77## Usage
78
79Here is a quick overview of how to use this package. For more detailed
80documentation, please see the [GoDoc Page](http://godoc.org/github.com/gofrs/uuid).
81
82```go
83package main
84
85import (
86 "log"
87
88 "github.com/gofrs/uuid"
89)
90
91// Create a Version 4 UUID, panicking on error.
92// Use this form to initialize package-level variables.
93var u1 = uuid.Must(uuid.NewV4())
94
95func main() {
96 // Create a Version 4 UUID.
97 u2, err := uuid.NewV4()
98 if err != nil {
99 log.Fatalf("failed to generate UUID: %v", err)
100 }
101 log.Printf("generated Version 4 UUID %v", u2)
102
103 // Parse a UUID from a string.
104 s := "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
105 u3, err := uuid.FromString(s)
106 if err != nil {
107 log.Fatalf("failed to parse UUID %q: %v", s, err)
108 }
109 log.Printf("successfully parsed UUID %v", u3)
110}
111```
112
113## References
114
115* [RFC-4122](https://tools.ietf.org/html/rfc4122)
116* [DCE 1.1: Authentication and Security Services](http://pubs.opengroup.org/onlinepubs/9696989899/chap5.htm#tagcjh_08_02_01_01)
117* [New UUID Formats RFC Draft (Peabody) Rev 03](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-03)
View as plain text