Configuring .deepsource.toml: Complete Reference Guide (2026)

Why the .deepsource.toml file matters

Every DeepSource analysis starts with one file: .deepsource.toml. This configuration file sits at the root of your repository and tells DeepSource which languages to analyze, which rules to apply, which files to skip, and which auto-formatting transformers to run. Without it, DeepSource cannot analyze your code at all. Get it wrong and you end up with hundreds of false positives from generated files, missing coverage on critical paths, or analyzers running against the wrong language version.

Despite its importance, the deepsource toml configuration is one of the most common sources of setup frustration. Teams copy a basic example from the documentation, commit it, and then spend hours troubleshooting why their Go analyzer is not picking up generated protobuf files or why their Python analysis is flagging syntax that is perfectly valid in Python 3.12. The configuration surface is deceptively simple - TOML is a straightforward format - but the interactions between analyzers, transformers, exclude patterns, and test patterns require careful planning.

This guide covers every section of the .deepsource.toml file in detail. You will learn how to configure analyzers for Python, JavaScript, Go, Java, Ruby, and Rust. You will set up transformers for automatic code formatting. You will define exclude patterns to eliminate noise and test patterns to separate test code from production code. And you will see complete, real-world examples for monorepos, multi-language projects, and specialized setups.

If you are new to DeepSource, start with our DeepSource review for an overview of the platform’s capabilities and limitations. If you have already decided on DeepSource and want to get it connected to your repositories, see our guide on DeepSource GitHub integration.

Basic .deepsource.toml file structure

The deepsource configuration file uses TOML (Tom’s Obvious, Minimal Language) syntax. At its simplest, the file requires only a version number and one analyzer definition. Here is the minimal valid configuration:

version = 1

[[analyzers]]
name = "python"
enabled = true

That three-line file is enough to activate Python analysis on your repository. But most real projects need significantly more configuration. The full structure of the file includes these top-level sections:

version = 1

exclude_patterns = [
  "vendor/**",
  "docs/**",
  "**/migrations/**",
]

test_patterns = [
  "tests/**",
  "**/*_test.py",
]

[[analyzers]]
name = "python"
enabled = true

  [analyzers.meta]
  runtime_version = "3.x"
  max_line_length = 100

[[analyzers]]
name = "javascript"
enabled = true

[[transformers]]
name = "black"
enabled = true

Let us break down each section.

Version

The version key is always set to 1. This is the only supported version value and must be present in every deepsource toml file. Omitting it or using a different number will cause a configuration error.

Exclude patterns

The exclude_patterns array tells DeepSource which files and directories to skip entirely during analysis. Patterns use glob syntax and are matched relative to the repository root. This is where you filter out generated code, vendor directories, build outputs, and any other files you do not want analyzed.

Test patterns

The test_patterns array identifies which files contain test code. These files are still analyzed, but DeepSource applies different rules to them - it will not flag hardcoded test data, relaxed complexity thresholds, or other patterns that are common and acceptable in tests but problematic in production code.

Analyzers

Each [[analyzers]] section defines a language-specific analysis engine. You can include as many analyzer sections as your project requires. The double-bracket TOML syntax [[analyzers]] creates an array of tables, meaning each occurrence adds a new analyzer to the list.

Transformers

Each [[transformers]] section enables an auto-formatting tool. When enabled, DeepSource creates pull requests with formatting fixes whenever it detects style violations that the transformer can resolve automatically. This ties directly into DeepSource autofix capabilities.

Analyzer configuration by language

The heart of any deepsource analyzer config is the language-specific settings within each [[analyzers]] block. Each analyzer has its own name, its own meta configuration options, and its own set of detection rules. Here is how to configure each supported language.

Python analyzer

Python is DeepSource’s most mature analyzer with the broadest rule coverage. The meta section for Python accepts several important options:

[[analyzers]]
name = "python"
enabled = true

  [analyzers.meta]
  runtime_version = "3.x"
  max_line_length = 100
  skip_doc_coverage = ["module", "magic", "init"]

The runtime_version field tells DeepSource which Python version your project targets. This affects which syntax features are considered valid - for example, structural pattern matching with match / case is only valid in Python 3.10 and later. If your project uses pyproject.toml, setup.cfg, or a Pipfile with a Python version specifier, DeepSource can infer this automatically, but setting it explicitly avoids ambiguity.

The max_line_length field controls the threshold for line-length warnings. The default is typically 79 (PEP 8 standard), but many modern Python projects use 88 (Black’s default) or 100-120 for wider monitors.

The skip_doc_coverage array lets you exclude certain types of functions from documentation coverage checks. Common values include module (module-level docstrings), magic (dunder methods like __init__ and __repr__), init (class __init__ methods specifically), and class (class docstrings).

For DeepSource Python analysis to work well, you should also specify your dependency file paths so DeepSource can understand your import structure:

[[analyzers]]
name = "python"
enabled = true

  [analyzers.meta]
  runtime_version = "3.x"
  max_line_length = 100
  dependency_file_paths = [
    "requirements.txt",
    "requirements-dev.txt",
    "pyproject.toml",
  ]

JavaScript and TypeScript analyzer

The JavaScript analyzer handles both JavaScript and TypeScript files automatically. DeepSource detects .ts, .tsx, .js, and .jsx files and applies the appropriate rules.

[[analyzers]]
name = "javascript"
enabled = true

  [analyzers.meta]
  plugins = ["react"]
  environment = ["browser", "node"]
  dialect = "flow"

The plugins array enables framework-specific rule sets. Supported values include react for React-specific analysis (hooks rules, JSX best practices), vue for Vue.js projects, and angular for Angular projects.

The environment array specifies the runtime environments your code targets, which affects which global variables are considered valid. Use browser for client-side code, node for server-side code, or both for universal/isomorphic projects.

The dialect field is typically set to flow only if your project uses Flow type annotations instead of TypeScript.

Go analyzer

The Go analyzer has specific meta options for controlling how DeepSource handles Go module paths and generated code:

[[analyzers]]
name = "go"
enabled = true

  [analyzers.meta]
  import_root = "github.com/your-org/your-repo"
  cgo_enabled = false
  skip_generated = true

The import_root field should match your Go module path as defined in go.mod. This helps DeepSource correctly resolve imports and distinguish between first-party and third-party packages.

Setting cgo_enabled to false tells DeepSource to skip analysis of CGO-dependent code paths, which is useful if your CI environment does not have a C compiler available.

The skip_generated option excludes files with the // Code generated comment header, which follows the Go convention for marking auto-generated code. This is essential for projects that use protobuf, gRPC code generation, or tools like go generate.

Java analyzer

The Java analyzer supports configuration for the Java version and build system:

[[analyzers]]
name = "java"
enabled = true

  [analyzers.meta]
  runtime_version = "17"

The runtime_version field accepts values like 8, 11, 17, or 21 corresponding to Java LTS releases. Setting this correctly ensures DeepSource understands newer Java syntax features like records (Java 16+), sealed classes (Java 17+), and pattern matching (Java 21+).

Ruby analyzer

The Ruby analyzer is straightforward with minimal meta configuration:

[[analyzers]]
name = "ruby"
enabled = true

DeepSource infers the Ruby version from your .ruby-version file or Gemfile if present. The Ruby analyzer covers style issues, performance anti-patterns, and common security vulnerabilities specific to the Ruby and Rails ecosystem.

Rust analyzer

The Rust analyzer handles Rust-specific concerns including unsafe code, lifetime issues, and performance patterns:

[[analyzers]]
name = "rust"
enabled = true

The Rust analyzer has fewer meta configuration options compared to Python or Go because Rust’s compiler already enforces strict correctness. DeepSource’s Rust analysis focuses on clippy-style lints, unsafe code usage, and idiomatic Rust patterns that the compiler does not catch.

Transformer setup and configuration

Transformers are DeepSource’s auto-formatting feature. When a transformer is enabled, DeepSource detects formatting violations and creates pull requests to fix them. This is one of the key differentiators covered in our DeepSource review - the ability to not just detect issues but automatically fix them.

Each transformer is defined in its own [[transformers]] section:

[[transformers]]
name = "black"
enabled = true

[[transformers]]
name = "isort"
enabled = true

[[transformers]]
name = "prettier"
enabled = true

[[transformers]]
name = "gofmt"
enabled = true

[[transformers]]
name = "rustfmt"
enabled = true

[[transformers]]
name = "rubocop"
enabled = true

Available transformers

Here is the full list of supported transformers and what they do:

Python transformers:

• black - Opinionated Python code formatter. Enforces consistent style with minimal configuration. Uses 88-character line length by default.
• autopep8 - Formats Python code to conform to PEP 8. Less opinionated than Black and offers more configuration options.
• isort - Sorts Python imports into sections (standard library, third-party, local) and alphabetizes within each section.
• yapf - Google’s Python formatter. Configurable via .style.yapf file.

JavaScript/TypeScript transformers:

• prettier - The standard formatter for JavaScript, TypeScript, JSON, CSS, HTML, and Markdown. Reads configuration from .prettierrc if present.

Go transformers:

• gofmt - The standard Go code formatter. Non-configurable and universally used in Go projects.
• gofumpt - A stricter version of gofmt with additional formatting rules.

Rust transformers:

• rustfmt - The standard Rust code formatter. Reads configuration from rustfmt.toml if present.

Ruby transformers:

• rubocop - Ruby code formatter and linter. Reads configuration from .rubocop.yml.

You should only enable transformers for languages that have a corresponding analyzer enabled. Enabling the Black transformer without the Python analyzer serves no purpose and can cause confusion in your deepsource configuration file.

Transformer and analyzer interaction

A common question is whether transformers and analyzers conflict with each other. They do not. The analysis pipeline runs analyzers first to detect issues, then runs transformers to generate fixes for formatting-related issues. However, you should make sure your transformer configuration matches your analyzer configuration. For example, if your Python analyzer has max_line_length = 100 but you are using Black (which defaults to 88), you will get conflicting signals about line length.

Exclude patterns in detail

The exclude_patterns section is critical for reducing noise in your deepsource toml configuration. Without proper exclusions, DeepSource will analyze generated code, vendored dependencies, build artifacts, and other files that produce hundreds of irrelevant findings.

exclude_patterns = [
  "vendor/**",
  "node_modules/**",
  "dist/**",
  "build/**",
  "*.min.js",
  "*.min.css",
  "**/*.pb.go",
  "**/migrations/**",
  "**/__generated__/**",
  "coverage/**",
  ".next/**",
  "public/assets/**",
]

Pattern syntax

Exclude patterns use standard glob syntax:

• * matches any sequence of characters within a single directory level
• ** matches any number of directories (recursive matching)
• ? matches a single character
• [abc] matches any character in the bracket set

Some important deepsource exclude files examples:

Pattern	What it excludes
vendor/**	Everything in the vendor directory
**/*.pb.go	All protobuf-generated Go files in any directory
*.min.js	All minified JavaScript files at the root level
**/migrations/**	All database migration files in any nested path
docs/**	All documentation files
**/fixtures/**	All test fixture directories

What to exclude and what not to exclude

Always exclude:

• Vendored or copied third-party code (vendor/**, third_party/**)
• Build output and compiled artifacts (dist/**, build/**, .next/**)
• Generated code (**/*.pb.go, **/__generated__/**, **/generated/**)
• Minified files (*.min.js, *.min.css)
• Package manager directories (node_modules/**)
• Coverage reports (coverage/**, htmlcov/**)

Never exclude:

• Your actual source code directories
• Configuration files (these often contain security issues)
• Infrastructure-as-code files (Terraform, Kubernetes manifests)
• Scripts and automation code

Use test_patterns instead of exclude_patterns for:

• Test files and test directories
• Test fixtures and mock data
• Integration test configurations

The distinction matters because excluded files are invisible to DeepSource while test-patterned files are analyzed with test-appropriate rules.

Test patterns configuration

Test patterns tell DeepSource which files are test code. This is separate from exclusion - test files are still analyzed, but with different rule sensitivity.

test_patterns = [
  "tests/**",
  "test/**",
  "spec/**",
  "**/*_test.py",
  "**/*_test.go",
  "**/*Test.java",
  "**/*.test.js",
  "**/*.test.ts",
  "**/*.spec.js",
  "**/*.spec.ts",
  "**/*_spec.rb",
]

The patterns you need depend on your project’s testing conventions. Python projects typically use tests/** or **/*_test.py. Go projects use **/*_test.go. JavaScript projects commonly use **/*.test.js or **/*.spec.js. Java projects follow the **/*Test.java convention.

Configuring test patterns correctly also affects test coverage metrics. DeepSource uses these patterns to determine which files should have coverage and which files are the tests themselves. Without correct test patterns, your coverage numbers will be skewed because test files will count toward the lines-to-cover total.

Dependency file paths

Specifying dependency file paths helps DeepSource understand your project’s dependency graph, which improves the accuracy of import analysis and vulnerability detection.

[[analyzers]]
name = "python"
enabled = true

  [analyzers.meta]
  dependency_file_paths = [
    "requirements.txt",
    "requirements-dev.txt",
    "setup.py",
    "pyproject.toml",
    "Pipfile",
  ]

For Python projects, DeepSource reads these files to understand which packages are available, their versions, and whether certain imports are valid. For JavaScript projects, package.json is typically detected automatically, but specifying it explicitly can help in monorepo setups where multiple package.json files exist at different levels.

Multi-analyzer setup for polyglot projects

Most modern projects use more than one language. A typical web application might have a Python or Go backend, a JavaScript or TypeScript frontend, and infrastructure code in multiple formats. The deepsource toml example below shows a full multi-analyzer configuration:

version = 1

exclude_patterns = [
  "vendor/**",
  "node_modules/**",
  "dist/**",
  "build/**",
  "**/*.pb.go",
  "**/migrations/**",
  "coverage/**",
  ".terraform/**",
  "*.min.js",
]

test_patterns = [
  "tests/**",
  "**/*_test.py",
  "**/*_test.go",
  "**/*.test.ts",
  "**/*.test.js",
  "**/*.spec.ts",
  "**/*.spec.js",
]

[[analyzers]]
name = "python"
enabled = true

  [analyzers.meta]
  runtime_version = "3.x"
  max_line_length = 100
  skip_doc_coverage = ["module", "magic", "init"]
  dependency_file_paths = ["requirements.txt", "pyproject.toml"]

[[analyzers]]
name = "go"
enabled = true

  [analyzers.meta]
  import_root = "github.com/your-org/your-project"
  skip_generated = true

[[analyzers]]
name = "javascript"
enabled = true

  [analyzers.meta]
  plugins = ["react"]
  environment = ["browser", "node"]

[[transformers]]
name = "black"
enabled = true

[[transformers]]
name = "isort"
enabled = true

[[transformers]]
name = "gofmt"
enabled = true

[[transformers]]
name = "prettier"
enabled = true

This configuration analyzes Python, Go, and JavaScript/TypeScript code in a single repository. Each analyzer runs independently and produces its own set of findings. The exclude and test patterns apply globally across all analyzers.

Monorepo considerations

In a monorepo where different services live in separate directories, you might want to scope your exclude and test patterns more precisely:

exclude_patterns = [
  "services/api/vendor/**",
  "services/web/node_modules/**",
  "services/web/dist/**",
  "services/worker/vendor/**",
  "infrastructure/.terraform/**",
]

test_patterns = [
  "services/api/tests/**",
  "services/api/**/*_test.go",
  "services/web/**/*.test.ts",
  "services/worker/tests/**",
  "services/worker/**/*_test.py",
]

This approach keeps each service’s exclusions and test patterns clearly scoped, making it easier to audit the configuration as the monorepo grows.

Real-world .deepsource.toml examples

Python Django project

version = 1

exclude_patterns = [
  "**/migrations/**",
  "staticfiles/**",
  "media/**",
  "htmlcov/**",
  "docs/**",
  "**/conftest.py",
  "manage.py",
]

test_patterns = [
  "**/tests/**",
  "**/test_*.py",
  "**/*_test.py",
  "tests/**",
]

[[analyzers]]
name = "python"
enabled = true

  [analyzers.meta]
  runtime_version = "3.x"
  max_line_length = 120
  skip_doc_coverage = ["module", "magic", "init"]
  dependency_file_paths = ["requirements.txt", "requirements-dev.txt"]

[[transformers]]
name = "black"
enabled = true

[[transformers]]
name = "isort"
enabled = true

Django projects need special attention to migration exclusions. Django auto-generates migration files, and analyzing them produces noise without value. The staticfiles and media directories contain user uploads and collected static assets that should never be analyzed.

Go microservice

version = 1

exclude_patterns = [
  "vendor/**",
  "**/*.pb.go",
  "**/*.pb.gw.go",
  "**/mock_*.go",
  "docs/**",
  "scripts/**",
]

test_patterns = [
  "**/*_test.go",
  "testdata/**",
]

[[analyzers]]
name = "go"
enabled = true

  [analyzers.meta]
  import_root = "github.com/your-org/payment-service"
  skip_generated = true
  cgo_enabled = false

[[transformers]]
name = "gofmt"
enabled = true

Go projects with gRPC or protobuf dependencies generate .pb.go and .pb.gw.go files that should always be excluded. Mock files generated by tools like mockgen follow the mock_*.go pattern and should also be excluded.

React TypeScript frontend

version = 1

exclude_patterns = [
  "node_modules/**",
  "dist/**",
  "build/**",
  "coverage/**",
  "public/**",
  "**/*.d.ts",
  "**/__snapshots__/**",
  "*.config.js",
  "*.config.ts",
]

test_patterns = [
  "**/*.test.ts",
  "**/*.test.tsx",
  "**/*.spec.ts",
  "**/*.spec.tsx",
  "src/__tests__/**",
  "src/__mocks__/**",
]

[[analyzers]]
name = "javascript"
enabled = true

  [analyzers.meta]
  plugins = ["react"]
  environment = ["browser"]

[[transformers]]
name = "prettier"
enabled = true

For React projects, excluding TypeScript declaration files (*.d.ts) and Jest snapshots (__snapshots__) is important. Declaration files are either auto-generated or come from type packages, and snapshot files are machine-generated test artifacts.

Ruby on Rails application

version = 1

exclude_patterns = [
  "vendor/**",
  "db/schema.rb",
  "db/migrate/**",
  "log/**",
  "tmp/**",
  "public/**",
  "bin/**",
  "node_modules/**",
]

test_patterns = [
  "spec/**",
  "test/**",
]

[[analyzers]]
name = "ruby"
enabled = true

[[transformers]]
name = "rubocop"
enabled = true

Rails projects should exclude db/schema.rb (auto-generated database schema), migration files, and the standard Rails directories that contain runtime artifacts rather than source code.

Common configuration mistakes

After working with many deepsource toml configuration files, certain mistakes appear repeatedly. Avoiding these will save you significant debugging time.

Mistake 1: Forgetting version = 1

Every .deepsource.toml file must start with version = 1. Without it, DeepSource will not parse the file and your repository will show zero analysis results. This is the most common cause of “DeepSource is not working” reports.

Mistake 2: Wrong analyzer names

Analyzer names must exactly match DeepSource’s expected values. Using "Python" instead of "python", "js" instead of "javascript", or "golang" instead of "go" will silently fail. The analyzer will not appear in your dashboard and no errors will be shown.

Mistake 3: Exclude patterns that are too broad

Patterns like **/*.py or src/** will exclude files you actually want analyzed. Always be specific with your exclusions. A pattern like **/generated/** is better than trying to match individual generated file extensions.

Mistake 4: Missing test patterns

Without test patterns, DeepSource applies production-level rules to your test code. This leads to noise - warnings about hardcoded values in test fixtures, complexity warnings in test setup methods, and documentation coverage flags on test functions. Always define test patterns to separate test code from production code.

Mistake 5: Conflicting transformer and analyzer settings

If your Python analyzer sets max_line_length = 120 but you enable the Black transformer (which defaults to 88 characters), DeepSource will simultaneously flag lines over 88 characters as formatting issues and accept lines up to 120 characters in the analyzer. Align these settings or configure Black’s line length in your pyproject.toml.

Mistake 6: Not excluding generated code

Generated files like protobuf outputs, GraphQL codegen results, OpenAPI client code, and database migration files should always be excluded. Analyzing them wastes processing time and fills your dashboard with findings you cannot fix because the source will be regenerated.

Mistake 7: Using exclude_patterns for test files

If you exclude test files instead of marking them as test patterns, DeepSource cannot calculate test coverage correctly. Test files should be analyzed - just with test-appropriate rules. Use test_patterns to identify them, not exclude_patterns to hide them.

Alternative: Zero-config analysis with CodeAnt AI

If managing a .deepsource.toml file across multiple repositories feels like unnecessary overhead, consider CodeAnt AI as an alternative. CodeAnt AI requires zero configuration files - no TOML, no YAML, no JSON configuration. It automatically detects your languages, frameworks, and project structure, and begins analyzing code immediately after connecting your repository.

CodeAnt AI is priced at $24-40/user/month depending on the plan and includes AI-powered code review, static analysis, and security scanning. Unlike DeepSource, where misconfigured analyzer settings can cause silent analysis failures, CodeAnt AI’s zero-config approach eliminates the entire class of configuration-related issues.

That said, the lack of a configuration file means less granular control. Teams that need precise exclusion patterns, specific language version targeting, or custom transformer setups will find DeepSource’s explicit configuration model more suitable. For a broader comparison, see our DeepSource alternatives roundup.

Validating and troubleshooting your configuration

After writing your .deepsource.toml file, follow these steps to verify it works correctly.

Step 1: Validate TOML syntax. Use a TOML validator to catch syntax errors before committing. Common issues include missing quotes around string values, incorrect bracket syntax for arrays and tables, and trailing commas (which are valid in JSON but not in TOML).

Step 2: Commit to your default branch. DeepSource reads the configuration file from your default branch (usually main or master). If you commit it to a feature branch, DeepSource will not pick it up until that branch is merged.

Step 3: Check the DeepSource dashboard. After committing, navigate to your repository on the DeepSource dashboard. The configuration section will display any errors or warnings about your file. Green status indicators mean the analyzers are configured correctly and running.

Step 4: Trigger a manual analysis. If you do not want to wait for the next commit, trigger a manual analysis run from the dashboard. This forces DeepSource to re-read the configuration and run all enabled analyzers immediately.

Step 5: Review the first results. Look at the initial findings for obvious configuration issues. If you see hundreds of findings in generated code, your exclude patterns need work. If you see test-related false positives, your test patterns are incomplete. If you see syntax errors in valid code, your runtime version setting might be wrong.

For ongoing configuration management, consider adding your .deepsource.toml file to code review. Changes to analyzer configuration can have significant effects on your team’s workflow - adding a new analyzer introduces new findings, changing exclude patterns can expose previously hidden issues, and modifying transformer settings changes auto-formatting behavior.

For details on what DeepSource costs across different team sizes, see our DeepSource pricing breakdown.

Summary

The .deepsource.toml file is small but consequential. A well-configured file means clean, relevant analysis results with minimal noise. A poorly configured file means hundreds of false positives, missing coverage on critical code paths, and transformers that fight your existing formatting standards.

Start with the minimal configuration - version = 1 and one analyzer - and expand from there. Add exclude patterns as you identify noise sources. Add test patterns to separate test code from production code. Enable transformers only after confirming they align with your existing formatting conventions. And use a multi-analyzer setup when your project spans multiple languages.

The key takeaway is that deepsource toml configuration is not a one-time task. As your project grows, your dependencies change, and your team adopts new tools, revisit the configuration to keep it aligned with your actual codebase structure. A quarterly review of your .deepsource.toml file takes five minutes and prevents the gradual accumulation of irrelevant findings that erode developer trust in the tool.