# carbon
**Repository Path**: dromara/carbon
## Basic Information
- **Project Name**: carbon
- **Description**: 轻量级、语义化、对开发者友好的 golang 时间处理库
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://carbon.go-pkg.com/zh
- **GVP Project**: Yes
## Statistics
- **Stars**: 438
- **Forks**: 71
- **Created**: 2020-09-07
- **Last Updated**: 2025-11-18
## Categories & Tags
**Categories**: utils
**Tags**: datetime, time, Carbon, go-carbon
## README
[](https://github.com/dromara/carbon/releases)
[](https://github.com/dromara/carbon/actions)
[](https://goreportcard.com/report/github.com/dromara/carbon/v2)
[](https://codecov.io/gh/dromara/carbon)
[](https://pkg.go.dev/github.com/dromara/carbon/v2)
[](https://github.com/avelino/awesome-go#date-and-time)
[](https://hellogithub.com/en/repository/dromara/carbon)
[](https://github.com/dromara/carbon/blob/master/LICENSE)
English | [简体中文](README.cn.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
## Introduction
`Carbon` is a lightweight, semantic, and developer-friendly `golang` time package that doesn't depend on `any` third-party package, has `100%` unit test coverage, and has been used by [docker](https://github.com/docker/docker-language-server/blob/main/go.mod#L10 "docker") organization as well as included by [awesome-go](https://github.com/yinggaozhen/awesome-go-cn#日期和时间 "awesome-go-cn") and [hello-github](https://hellogithub.com/repository/dromara/carbon "hello-github").
## Repository
[github.com/dromara/carbon](https://github.com/dromara/carbon "github.com/dromara/carbon")
[gitee.com/dromara/carbon](https://gitee.com/dromara/carbon "gitee.com/dromara/carbon")
[gitcode.com/dromara/carbon](https://gitcode.com/dromara/carbon "gitcode.com/dromara/carbon")
## Quick Start
### Installation
> go version >= 1.18
```go
// Via github
go get -u github.com/dromara/carbon/v2
import "github.com/dromara/carbon/v2"
// Via gitee
go get -u gitee.com/dromara/carbon/v2
import "gitee.com/dromara/carbon/v2"
// Via gitcode
go get -u gitcode.com/dromara/carbon/v2
import "gitcode.com/dromara/gitcode/v2"
```
`Carbon` was donated to the [dromara](https://dromara.org/ "dromara") organization, the repository URL has changed. If
the previous repository used was `golang-module/carbon`, please replace the original repository with the new repository
in `go.mod`, or execute the following command:
```go
go mod edit -replace github.com/golang-module/carbon/v2 = github.com/dromara/carbon/v2
```
### Example Usage
Default timezone is `UTC`, language locale is `English`, start day of the week is `Monday` and weekend days of the week
are `Saturday` and `Sunday`.
```go
carbon.SetTestNow(carbon.Parse("2020-08-05 13:14:15.999999999"))
carbon.IsTestNow() // true
carbon.Now().ToString() // 2020-08-05 13:14:15.999999999 +0000 UTC
carbon.Yesterday().ToString() // 2020-08-04 13:14:15.999999999 +0000 UTC
carbon.Tomorrow().ToString() // 2020-08-06 13:14:15.999999999 +0000 UTC
carbon.Parse("2020-08-05 13:14:15").ToString() // 2020-08-05 13:14:15 +0000 UTC
carbon.Parse("2022-03-08T03:01:14-07:00").ToString() // 2022-03-08 10:01:14 +0000 UTC
carbon.ParseByLayout("It is 2020-08-05 13:14:15", "It is 2006-01-02 15:04:05").ToString() // 2020-08-05 13:14:15 +0000 UTC
carbon.ParseByFormat("It is 2020-08-05 13:14:15", "\\I\\t \\i\\s Y-m-d H:i:s").ToString() // 2020-08-05 13:14:15 +0000 UTC
carbon.CreateFromDate(2020, 8, 5).ToString() // 2020-08-05 00:00:00 +0000 UTC
carbon.CreateFromTime(13, 14, 15).ToString() // 2020-08-05 13:14:15 +0000 UTC
carbon.CreateFromDateTime(2020, 8, 5, 13, 14, 15).ToString() // 2020-08-05 13:14:15 +0000 UTC
carbon.CreateFromTimestamp(1596633255).ToString() // 2020-08-05 13:14:15 +0000 UTC
carbon.Parse("2020-07-05 13:14:15").DiffForHumans() // 1 month before
carbon.Parse("2020-07-05 13:14:15").SetLocale("zh-CN").DiffForHumans() // 1 月前
carbon.ClearTestNow()
carbon.IsTestNow() // false
```
For more usage examples, please refer to official document.
For performance test reports, please refer to [benchmark report](docs/BENCHMARK.en.md)
## References
* [briannesbitt/carbon](https://github.com/briannesbitt/Carbon)
* [nodatime/nodatime](https://github.com/nodatime/nodatime)
* [jinzhu/now](https://github.com/jinzhu/now)
* [goframe/gtime](https://github.com/gogf/gf/tree/master/os/gtime)
* [jodaOrg/joda-time](https://github.com/jodaOrg/joda-time)
* [arrow-py/arrow](https://github.com/arrow-py/arrow)
* [moment/moment](https://github.com/moment/moment)
* [iamkun/dayjs](https://github.com/iamkun/dayjs)
## Contributors
Thanks to all the following who contributed to `Carbon`:
## Translators
Ask for help to translate `Carbon` in other localized languages
[How to add new localized language support to carbon](https://carbon.go-pkg.com/appendix/contribution-guide.html)
## Sponsors
`Carbon` is a non-commercial open source project. If you want to support `Carbon`, you can [buy a cup of coffee](https://carbon.go-pkg.com/sponsor.html) for developer.
## Thanks
`Carbon` had been being developed with GoLand under the free JetBrains Open Source license, I would like to express my
thanks here.
## License
`Carbon` is licensed under the `MIT` License, see the [LICENSE](./LICENSE) file for details.