golangci-lint

Configuration

Table of Contents

The config file has lower priority than command-line options. If the same bool/string/int option is provided on the command-line and in the config file, the option from command-line will be used. Slice options (e.g. list of enabled/disabled linters) are combined from the command-line and config file.

To see a list of linters enabled by your configuration use:

golangci-lint linters

To see a list of formatters enabled by your configuration use:

golangci-lint formatters

Config 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 description, 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: https://golangci-lint.run/jsonschema/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`, `all`, `none`, or `fast`.
  # Default: standard
  default: all
  # Enable specific linter.
  # https://golangci-lint.run/usage/linters/#enabled-by-default
  enable:
    - asasalint
    - asciicheck
    - bidichk
    - bodyclose
    - canonicalheader
    - containedctx
    - contextcheck
    - copyloopvar
    - cyclop
    - decorder
    - depguard
    - dogsled
    - dupl
    - dupword
    - durationcheck
    - 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
    - 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
    - zerologlint
  # Disable specific linter.
  # https://golangci-lint.run/usage/linters/#disabled-by-default
  disable:
    - asasalint
    - asciicheck
    - bidichk
    - bodyclose
    - canonicalheader
    - containedctx
    - contextcheck
    - copyloopvar
    - cyclop
    - decorder
    - depguard
    - dogsled
    - dupl
    - dupword
    - durationcheck
    - 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
    - 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
    - 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
  # 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.
    # 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

Command-Line Options

run

$ golangci-lint run -h
Usage:
  golangci-lint run [flags]


Flags:
  -c, --config PATH                       Read config from file path PATH
      --no-config                         Don't read config file
      --default string                    Default set of linters to enable (default "standard")
  -D, --disable strings                   Disable specific linter
  -E, --enable strings                    Enable specific linter
      --enable-only strings               Override linters configuration section to only run the specific linter(s)
      --fast-only                         Filter enabled linters to run only fast linters
  -j, --concurrency int                   Number of CPUs to use (Default: Automatically set to match Linux container CPU quota and fall back to the number of logical CPUs in the machine)
      --modules-download-mode string      Modules download mode. If not empty, passed as -mod=<mode> to go tools
      --issues-exit-code int              Exit code when issues were found (default 1)
      --build-tags strings                Build tags
      --timeout duration                  Timeout for total work. Disabled by default
      --tests                             Analyze tests (*_test.go) (default true)
      --allow-parallel-runners            Allow multiple parallel golangci-lint instances running.
                                          If false (default) - golangci-lint acquires file lock on start.
      --allow-serial-runners              Allow multiple golangci-lint instances running, but serialize them around a lock.
                                          If false (default) - golangci-lint exits with an error if it fails to acquire file lock on start.
      --path-prefix string                Path prefix to add to output
      --path-mode string                  Path mode to use (empty, or 'abs')
      --show-stats                        Show statistics per linter (default true)
      --output.text.path stdout           Output path can be either stdout, `stderr` or path to the file to write to.
      --output.text.print-linter-name     Print linter name in the end of issue text. (default true)
      --output.text.print-issued-lines    Print lines of code with issue. (default true)
      --output.text.colors                Use colors. (default true)
      --output.json.path stdout           Output path can be either stdout, `stderr` or path to the file to write to.
      --output.tab.path stdout            Output path can be either stdout, `stderr` or path to the file to write to.
      --output.tab.print-linter-name      Print linter name in the end of issue text. (default true)
      --output.tab.colors                 Use colors. (default true)
      --output.html.path stdout           Output path can be either stdout, `stderr` or path to the file to write to.
      --output.checkstyle.path stdout     Output path can be either stdout, `stderr` or path to the file to write to.
      --output.code-climate.path stdout   Output path can be either stdout, `stderr` or path to the file to write to.
      --output.junit-xml.path stdout      Output path can be either stdout, `stderr` or path to the file to write to.
      --output.junit-xml.extended         Support extra JUnit XML fields.
      --output.teamcity.path stdout       Output path can be either stdout, `stderr` or path to the file to write to.
      --output.sarif.path stdout          Output path can be either stdout, `stderr` or path to the file to write to.
      --max-issues-per-linter int         Maximum issues count per one linter. Set to 0 to disable (default 50)
      --max-same-issues int               Maximum count of issues with the same text. Set to 0 to disable (default 3)
      --uniq-by-line                      Make issues output unique by line (default true)
  -n, --new                               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 to not allow issues in new code.
                                          For CI setups, prefer --new-from-rev=HEAD~, as --new can skip linting the current patch if any scripts generate unstaged files before golangci-lint runs.
      --new-from-rev REV                  Show only new issues created after git revision REV
      --new-from-patch PATH               Show only new issues created in git patch with file path PATH
      --new-from-merge-base string        Show only new issues created after the best common ancestor (merge-base against HEAD)
      --whole-files                       Show issues in any part of update files (requires new-from-rev or new-from-patch)
      --fix                               Fix found issues (if it's supported by the linter)
      --cpu-profile-path string           Path to CPU profile output file
      --mem-profile-path string           Path to memory profile output file
      --print-resources-usage             Print avg and max memory usage of golangci-lint and total time
      --trace-path string                 Path to trace output file


Global Flags:
      --color string   Use color when printing; can be 'always', 'auto', or 'never' (default "auto")
  -h, --help           Help for a command
  -v, --verbose        Verbose output

When the --cpu-profile-path or --mem-profile-path arguments are specified, golangci-lint writes runtime profiling data in the format expected by the pprof visualization tool.

When the --trace-path argument is specified, golangci-lint writes runtime tracing data in the format expected by the go tool trace command and visualization tool.

fmt

$ golangci-lint fmt -h
Usage:
  golangci-lint fmt [flags]


Flags:
  -c, --config PATH      Read config from file path PATH
      --no-config        Don't read config file
  -E, --enable strings   Enable specific formatter
  -d, --diff             Display diffs instead of rewriting files
      --diff-colored     Display diffs instead of rewriting files (with colors)
      --stdin            Use standard input for piping source files


Global Flags:
      --color string   Use color when printing; can be 'always', 'auto', or 'never' (default "auto")
  -h, --help           Help for a command
  -v, --verbose        Verbose output

Cache

Golangci-lint stores its cache in the subdirectory golangci-lint inside the default user cache directory.

You can override the default cache directory with the environment variable GOLANGCI_LINT_CACHE; the path must be absolute.

Edit this page on GitHub

Prev

Documentation v1

Next

Linters