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
Last updated on