https://github.com/dromara/carbon

A simple, semantic and developer-friendly time package for golang
https://github.com/dromara/carbon

calendar carbon date datetime gorm hebrew i18n jalaali julian lunar persian time timezone xorm

Last synced: 22 days ago
JSON representation

A simple, semantic and developer-friendly time package for golang

• Host: GitHub
• URL: https://github.com/dromara/carbon
• Owner: dromara
• License: mit
• Created: 2020-09-07T09:07:35.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2026-10-03T23:01:50.000Z (about 1 month ago)
• Last Synced: 2026-10-04T11:44:34.092Z (about 1 month ago)
• Topics: calendar, carbon, date, datetime, gorm, hebrew, i18n, jalaali, julian, lunar, persian, time, timezone, xorm
• Language: Go
• Homepage: https://carbon.go-pkg.com
• Size: 5.74 MB
• Stars: 5,224
• Watchers: 27
• Forks: 271
• Open Issues: 3
• Metadata Files:
  • Readme: README.cn.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

• awesome-go - dromara/carbon - friendly time package for golang ☆`5,189` (Date and Time / Search and Analytic Databases)
• my-awesome - dromara/carbon - 10 star:5.2k fork:0.3k A simple, semantic and developer-friendly time package for golang (Go)
• awesome-go-plus - carbon - A simple, semantic and developer-friendly time package for golang.  (Date and Time / Search and Analytic Databases)
• awesome-go - dromara/carbon - A simple, semantic and developer-friendly time package for golang (Other / General Purpose Libraries)
• awesome-go-with-stars - carbon - friendly time package for golang. | 2026-10-10 | (Date and Time / Search and Analytic Databases)
• fucking-awesome-go - carbon - A simple, semantic and developer-friendly time package for golang. (Date and Time / Search and Analytic Databases)
• awesome-go - carbon - A simple, semantic and developer-friendly time package for golang. (Date and Time / Search and Analytic Databases)
• awesome-go-cn - carbon - friendly time package for golang. [![近一周有更新][G]](https://github.com/dromara/carbon) [![godoc][D]](https://godoc.org/github.com/dromara/carbon) [![包含中文文档][CN]](https://github.com/dromara/carbon) (日期和时间 / 检索及分析资料库)
• awesome-go - carbon - A simple, semantic and developer-friendly time package for golang. Stars:`5.1K`. (Date and Time / Search and Analytic Databases)
• awesome-go-cn - carbon - friendly time package for golang. [![近一周有更新][G]](https://github.com/dromara/carbon) [![godoc][D]](https://godoc.org/github.com/dromara/carbon) [![包含中文文档][CN]](https://github.com/dromara/carbon) (日期和时间 / 检索及分析资料库)

README

          




[![Carbon Release](https://img.shields.io/github/release/dromara/carbon.svg)](https://github.com/dromara/carbon/releases)

[![Go Test](https://github.com/dromara/carbon/actions/workflows/test.yml/badge.svg)](https://github.com/dromara/carbon/actions)

[![Go Coverage](https://codecov.io/gh/dromara/carbon/branch/master/graph/badge.svg)](https://codecov.io/gh/dromara/carbon)

[![Carbon Doc](https://img.shields.io/badge/go.dev-reference-brightgreen?logo=go&logoColor=white&style=flat)](https://pkg.go.dev/github.com/dromara/carbon/v2)

[![Awesome](https://awesome.re/badge-flat2.svg)](https://github.com/avelino/awesome-go#date-and-time)

[![HelloGitHub](https://api.hellogithub.com/v1/widgets/recommend.svg?rid=0eddd8c3469549b7b246f85a83d1c42e&claim_uid=kKBvMpyxSgLhmJO&theme=small)](https://hellogithub.com/en/repository/dromara/carbon)

[![License](https://img.shields.io/github/license/dromara/carbon)](https://github.com/dromara/carbon/blob/master/LICENSE)

简体中文 | [English](README.md) | [日本語](README.ja.md) | [한국어](README.ko.md)

## 项目简介

`Carbon` 是一个轻量级、语义化、对开发者友好的 `golang` 时间处理库，不依赖于 `任何` 第三方库， `100%` 单元测试覆盖率，已被 [docker](https://github.com/docker/docker-language-server/blob/main/go.mod#L10 "docker") 组织使用以及被 [awesome-go](https://github.com/yinggaozhen/awesome-go-cn#日期和时间 "awesome-go-cn") 和 [hello-github](https://hellogithub.com/repository/dromara/carbon "hello-github") 收录，并获得

`gitee` 2024 年最有价值项目（`GVP`）和 `gitcode` 2024 年度开源摘星计划 (`G-Star`) 项目







## 仓库地址

[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")

## 快速开始

### 安装使用

> go version >= 1.18

```go

// 使用 github 库

go get -u github.com/dromara/carbon/v2

import "github.com/dromara/carbon/v2"

// 使用 gitee 库

go get -u gitee.com/dromara/carbon/v2

import "gitee.com/dromara/carbon/v2"

// 使用 gitcode 库

go get -u gitcode.com/dromara/carbon/v2

import "gitcode.com/dromara/carbon/v2"

```

`Carbon` 已经捐赠给了 [dromara](https://dromara.org/ "dromara") 开源组织，仓库地址发生了改变，如果之前用的路径是

`golang-module/carbon`，请在 `go.mod` 里将原地址更换为新路径，或执行如下命令

```go

go mod edit -replace github.com/golang-module/carbon/v2 = github.com/dromara/carbon/v2

```

### 用法示例

默认时区是 `UTC`, 语言环境是 `英语`，一周开始日期是 `周一`，周末是 `周六`和 `周日`。

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

```

更多用法示例请查看 官方文档，性能测试报告请查看 [分析报告](docs/BENCHMARK.cn.md)

## 参考项目

* [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)

## 贡献者

感谢以下所有为 `Carbon` 做出贡献的人：



## 翻译者

欢迎帮助将 `Carbon` 翻译为更多本地化语言

[如何为 carbon 添加新的本地化语言支持](https://carbon.go-pkg.com/zh/appendix/contribution-guide.html)

## 赞助

`Carbon` 是一个非商业开源项目, 如果你想支持 `Carbon`,

你可以为开发者 [购买一杯咖啡](https://carbon.go-pkg.com/zh/sponsor.html) 或 点击以下赞助广告

- **Easysearch**  

  企业级的分布式搜索型数据库，ES 国产化的首选替代方案

  

- **雨云**  

  KVM高配版，4核 8G 300M，仅需68元/月起，半年付八折，年付七折，七天无理由退订（送5折券）  

  [点击购买](https://www.rainyun.com/gopkg_?s=github)

## 致谢

`Carbon`已获取免费的 JetBrains 开源许可证，在此表示感谢



## 开源协议

`Carbon` 遵循 `MIT` 开源协议, 请参阅 [LICENSE](./LICENSE) 查看详细信息。