Configuration File
Golangci-lint looks for config files in the following paths from the current working directory:
.golangci.yml
.golangci.yaml
.golangci.toml
.golangci.json
Golangci-lint also searches for config files in all directories from the directory of the first analyzed path up to the root.
If no configuration file has been found, golangci-lint will try to find one in your home directory.
To see which config file is being used and where it was sourced from run golangci-lint with -v
option.
Config options inside the file are identical to command-line options. You can configure specific linters’ options only within the config file (not the command-line).
There is a .golangci.reference.yml
file with all supported options, their descriptions, and default values.
This file is neither a working example nor a recommended configuration, it’s just a reference to display all the configuration options.
The configuration file can be validated with the JSON Schema: golangci.jsonschema.json
# See the dedicated "version" documentation section.
version: "2"
linters:
# See the dedicated "linters" documentation section.
option: value
formatters:
# See the dedicated "formatters" documentation section.
option: value
issues:
# See the dedicated "issues" documentation section.
option: value
# Output configuration options.
output:
# See the dedicated "output" documentation section.
option: value
# Options for analysis running.
run:
# See the dedicated "run" documentation section.
option: value
severity:
# See the dedicated "severity" documentation section.
option: value
version
configuration
# Defines the configuration version.
# The only possible value is "2".
version: "2"
linters
configuration
linters:
# Default set of linters.
# The value can be:
# - `standard`: https://golangci-lint.run/docs/linters/#enabled-by-default
# - `all`: enables all linters by default.
# - `none`: disables all linters by default.
# - `fast`: enables only linters considered as "fast" (`golangci-lint help linters --json | jq '[ .[] | select(.fast==true) ] | map(.name)'`).
# Default: standard
default: all
# Enable specific linter.
enable:
- arangolint
- asasalint
- asciicheck
- bidichk
- bodyclose
- canonicalheader
- containedctx
- contextcheck
- copyloopvar
- cyclop
- decorder
- depguard
- dogsled
- dupl
- dupword
- durationcheck
- embeddedstructfieldcheck
- err113
- errcheck
- errchkjson
- errname
- errorlint
- exhaustive
- exhaustruct
- exptostd
- fatcontext
- forbidigo
- forcetypeassert
- funcorder
- funlen
- ginkgolinter
- gocheckcompilerdirectives
- gochecknoglobals
- gochecknoinits
- gochecksumtype
- gocognit
- goconst
- gocritic
- gocyclo
- godot
- godox
- goheader
- gomoddirectives
- gomodguard
- goprintffuncname
- gosec
- gosmopolitan
- govet
- grouper
- iface
- importas
- inamedparam
- ineffassign
- interfacebloat
- intrange
- ireturn
- lll
- loggercheck
- maintidx
- makezero
- mirror
- misspell
- mnd
- musttag
- nakedret
- nestif
- nilerr
- nilnesserr
- nilnil
- nlreturn
- noctx
- noinlineerr
- nolintlint
- nonamedreturns
- nosprintfhostport
- paralleltest
- perfsprint
- prealloc
- predeclared
- promlinter
- protogetter
- reassign
- recvcheck
- revive
- rowserrcheck
- sloglint
- spancheck
- sqlclosecheck
- staticcheck
- tagalign
- tagliatelle
- testableexamples
- testifylint
- testpackage
- thelper
- tparallel
- unconvert
- unparam
- unused
- usestdlibvars
- usetesting
- varnamelen
- wastedassign
- whitespace
- wrapcheck
- wsl
- wsl_v5
- zerologlint
# Disable specific linters.
disable:
- arangolint
- asasalint
- asciicheck
- bidichk
- bodyclose
- canonicalheader
- containedctx
- contextcheck
- copyloopvar
- cyclop
- decorder
- depguard
- dogsled
- dupl
- dupword
- durationcheck
- embeddedstructfieldcheck
- err113
- errcheck
- errchkjson
- errname
- errorlint
- exhaustive
- exhaustruct
- exptostd
- fatcontext
- forbidigo
- forcetypeassert
- funcorder
- funlen
- ginkgolinter
- gocheckcompilerdirectives
- gochecknoglobals
- gochecknoinits
- gochecksumtype
- gocognit
- goconst
- gocritic
- gocyclo
- godot
- godox
- goheader
- gomoddirectives
- gomodguard
- goprintffuncname
- gosec
- gosmopolitan
- govet
- grouper
- iface
- importas
- inamedparam
- ineffassign
- interfacebloat
- intrange
- ireturn
- lll
- loggercheck
- maintidx
- makezero
- mirror
- misspell
- mnd
- musttag
- nakedret
- nestif
- nilerr
- nilnesserr
- nilnil
- nlreturn
- noctx
- noinlineerr
- nolintlint
- nonamedreturns
- nosprintfhostport
- paralleltest
- perfsprint
- prealloc
- predeclared
- promlinter
- protogetter
- reassign
- recvcheck
- revive
- rowserrcheck
- sloglint
- spancheck
- sqlclosecheck
- staticcheck
- tagalign
- tagliatelle
- testableexamples
- testifylint
- testpackage
- thelper
- tparallel
- unconvert
- unparam
- unused
- usestdlibvars
- usetesting
- varnamelen
- wastedassign
- whitespace
- wrapcheck
- wsl
- wsl_v5
- zerologlint
# All available settings of specific linters.
settings:
# See the dedicated "linters.settings" documentation section.
option: value
# Defines a set of rules to ignore issues.
# It does not skip the analysis, and so does not ignore "typecheck" errors.
exclusions:
# Mode of the generated files analysis.
#
# - `strict`: sources are excluded by strictly following the Go generated file convention.
# Source files that have lines matching only the following regular expression will be excluded: `^// Code generated .* DO NOT EDIT\.$`
# This line must appear before the first non-comment, non-blank text in the file.
# https://go.dev/s/generatedcode
# - `lax`: sources are excluded if they contain lines like `autogenerated file`, `code generated`, `do not edit`, etc.
# - `disable`: disable the generated files exclusion.
#
# Default: strict
generated: lax
# Log a warning if an exclusion rule is unused.
# Default: false
warn-unused: true
# Predefined exclusion rules.
# Default: []
presets:
- comments
- std-error-handling
- common-false-positives
- legacy
# Excluding configuration per-path, per-linter, per-text and per-source.
rules:
# Exclude some linters from running on tests files.
- path: _test\.go
linters:
- gocyclo
- errcheck
- dupl
- gosec
# Run some linter only for test files by excluding its issues for everything else.
- path-except: _test\.go
linters:
- forbidigo
# Exclude known linters from partially hard-vendored code,
# which is impossible to exclude via `nolint` comments.
# `/` will be replaced by the current OS file path separator to properly work on Windows.
- path: internal/hmac/
text: "weak cryptographic primitive"
linters:
- gosec
# Exclude some `staticcheck` messages.
- linters:
- staticcheck
text: "SA9003:"
# Exclude `lll` issues for long lines with `go:generate`.
- linters:
- lll
source: "^//go:generate "
# Which file paths to exclude: they will be analyzed, but issues from them won't be reported.
# "/" will be replaced by the current OS file path separator to properly work on Windows.
# Default: []
paths:
- ".*\\.my\\.go$"
- lib/bad.go
# Which file paths to not exclude.
# Default: []
paths-except:
- ".*\\.my\\.go$"
- lib/bad.go
formatters
configuration
formatters:
# Enable specific formatter.
# Default: [] (uses standard Go formatting)
enable:
- gci
- gofmt
- gofumpt
- goimports
- golines
- swaggo
# Formatters settings.
settings:
# See the dedicated "formatters.settings" documentation section.
option: value
exclusions:
# Log a warning if an exclusion path is unused.
# Default: false
warn-unused: true
# Mode of the generated files analysis.
#
# - `strict`: sources are excluded by strictly following the Go generated file convention.
# Source files that have lines matching only the following regular expression will be excluded: `^// Code generated .* DO NOT EDIT\.$`
# This line must appear before the first non-comment, non-blank text in the file.
# https://go.dev/s/generatedcode
# - `lax`: sources are excluded if they contain lines like `autogenerated file`, `code generated`, `do not edit`, etc.
# - `disable`: disable the generated files exclusion.
#
# Default: lax
generated: strict
# Which file paths to exclude.
# This option is ignored when using `--stdin` as the path is unknown.
# Default: []
paths:
- ".*\\.my\\.go$"
- lib/bad.go
issues
configuration
issues:
# Maximum issues count per one linter.
# Set to 0 to disable.
# Default: 50
max-issues-per-linter: 0
# Maximum count of issues with the same text.
# Set to 0 to disable.
# Default: 3
max-same-issues: 0
# Make issues output unique by line.
# Default: true
uniq-by-line: false
# Show only new issues: if there are unstaged changes or untracked files,
# only those changes are analyzed, else only changes in HEAD~ are analyzed.
# It's a super-useful option for integration of golangci-lint into existing large codebase.
# It's not practical to fix all existing issues at the moment of integration:
# much better don't allow issues in new code.
#
# Default: false
new: true
# Show only new issues created after the best common ancestor (merge-base against HEAD).
# Default: ""
new-from-merge-base: main
# Show only new issues created after git revision `REV`.
# Default: ""
new-from-rev: HEAD
# Show only new issues created in git patch with set file path.
# Default: ""
new-from-patch: path/to/patch/file
# Show issues in any part of update files (requires new-from-rev or new-from-patch).
# Default: false
whole-files: true
# Fix found issues (if it's supported by the linter).
# Default: false
fix: true
output
configuration
# Output configuration options.
output:
# The formats used to render issues.
formats:
# Prints issues in a text format with colors, line number, and linter name.
# This format is the default format.
text:
# Output path can be either `stdout`, `stderr` or path to the file to write to.
# Default: stdout
path: ./path/to/output.txt
# Print linter name in the end of issue text.
# Default: true
print-linter-name: false
# Print lines of code with issue.
# Default: true
print-issued-lines: false
# Use colors.
# Default: true
colors: false
# Prints issues in a JSON representation.
json:
# Output path can be either `stdout`, `stderr` or path to the file to write to.
# Default: stdout
path: ./path/to/output.json
# Prints issues in columns representation separated by tabulations.
tab:
# Output path can be either `stdout`, `stderr` or path to the file to write to.
# Default: stdout
path: ./path/to/output.txt
# Print linter name in the end of issue text.
# Default: true
print-linter-name: true
# Use colors.
# Default: true
colors: false
# Prints issues in an HTML page.
# It uses the Cloudflare CDN (cdnjs) and React.
html:
# Output path can be either `stdout`, `stderr` or path to the file to write to.
# Default: stdout
path: ./path/to/output.html
# Prints issues in the Checkstyle format.
checkstyle:
# Output path can be either `stdout`, `stderr` or path to the file to write to.
# Default: stdout
path: ./path/to/output.xml
# Prints issues in the Code Climate format.
code-climate:
# Output path can be either `stdout`, `stderr` or path to the file to write to.
# Default: stdout
path: ./path/to/output.json
# Prints issues in the JUnit XML format.
junit-xml:
# Output path can be either `stdout`, `stderr` or path to the file to write to.
# Default: stdout
path: ./path/to/output.xml
# Support extra JUnit XML fields.
# Default: false
extended: true
# Prints issues in the TeamCity format.
teamcity:
# Output path can be either `stdout`, `stderr` or path to the file to write to.
# Default: stdout
path: ./path/to/output.txt
# Prints issues in the SARIF format.
sarif:
# Output path can be either `stdout`, `stderr` or path to the file to write to.
# Default: stdout
path: ./path/to/output.json
# Add a prefix to the output file references.
# This option is ignored when using `output.path-mode: abs` mode.
# Default: ""
path-prefix: ""
# By default, the report are related to the path obtained by `run.relative-path-mode`.
# The mode `abs` allows to show absolute file paths instead of relative file paths.
# The option `output.path-prefix` is ignored when using `abs` mode.
# Default: ""
path-mode: "abs"
# Order to use when sorting results.
# Possible values: `file`, `linter`, and `severity`.
#
# If the severity values are inside the following list, they are ordered in this order:
# 1. error
# 2. warning
# 3. high
# 4. medium
# 5. low
# Either they are sorted alphabetically.
#
# Default: ["linter", "file"]
sort-order:
- linter
- severity
- file # filepath, line, and column.
# Show statistics per linter.
# Default: true
show-stats: false
run
configuration
# Options for analysis running.
run:
# Timeout for total work, e.g. 30s, 5m, 5m30s.
# If the value is lower or equal to 0, the timeout is disabled.
# Default: 0 (disabled)
timeout: 5m
# The mode used to evaluate relative paths.
# It's used by exclusions, Go plugins, and some linters.
# The value can be:
# - `gomod`: the paths will be relative to the directory of the `go.mod` file.
# - `gitroot`: the paths will be relative to the git root (the parent directory of `.git`).
# - `cfg`: the paths will be relative to the configuration file.
# - `wd` (NOT recommended): the paths will be relative to the place where golangci-lint is run.
# Default: cfg
relative-path-mode: gomod
# Exit code when at least one issue was found.
# Default: 1
issues-exit-code: 2
# Include test files or not.
# Default: true
tests: false
# List of build tags, all linters use it.
# Default: []
build-tags:
- mytag
# If set, we pass it to "go list -mod={option}". From "go help modules":
# If invoked with -mod=readonly, the go command is disallowed from the implicit
# automatic updating of go.mod described above. Instead, it fails when any changes
# to go.mod are needed. This setting is most useful to check that go.mod does
# not need updates, such as in a continuous integration and testing system.
# If invoked with -mod=vendor, the go command assumes that the vendor
# directory holds the correct copies of dependencies and ignores
# the dependency descriptions in go.mod.
#
# Allowed values: readonly|vendor|mod
# Default: ""
modules-download-mode: readonly
# Allow multiple parallel golangci-lint instances running.
# If false, golangci-lint acquires file lock on start.
# Default: false
allow-parallel-runners: true
# Allow multiple golangci-lint instances running, but serialize them around a lock.
# If false, golangci-lint exits with an error if it fails to acquire file lock on start.
# Default: false
allow-serial-runners: true
# Define the Go version limit.
# Default: use Go version from the go.mod file, fallback on the env var `GOVERSION`, fallback on 1.22.
go: '1.23'
# Number of operating system threads (`GOMAXPROCS`) that can execute golangci-lint simultaneously.
# Default: 0 (automatically set to match Linux container CPU quota and
# fall back to the number of logical CPUs in the machine)
concurrency: 4
severity
configuration
severity:
# Set the default severity for issues.
#
# If severity rules are defined and the issues do not match or no severity is provided to the rule
# this will be the default severity applied.
# Severities should match the supported severity names of the selected out format.
# - Code climate: https://docs.codeclimate.com/docs/issues#issue-severity
# - Checkstyle: https://checkstyle.sourceforge.io/property_types.html#SeverityLevel
# - GitHub: https://help.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-error-message
# - TeamCity: https://www.jetbrains.com/help/teamcity/service-messages.html#Inspection+Instance
#
# `@linter` can be used as severity value to keep the severity from linters (e.g. revive, gosec, ...)
#
# Default: ""
default: error
# When a list of severity rules are provided, severity information will be added to lint issues.
# Severity rules have the same filtering capability as exclude rules
# except you are allowed to specify one matcher per severity rule.
#
# `@linter` can be used as severity value to keep the severity from linters (e.g. revive, gosec, ...)
#
# Only affects out formats that support setting severity information.
#
# Default: []
rules:
- linters:
- dupl
severity: info