Install & Compatibility
Where this runs
tested against v1.5.50 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.566s · 24.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.4s · import 0.525s · 26MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SecretsCollection
✓ from detect_secrets import SecretsCollection
Used for programmatic collection and management of detected secrets.
transient_settings
✓ from detect_secrets.settings import transient_settings
Context manager for temporarily modifying detect-secrets settings, such as plugin configurations.
plugins
✓ from detect_secrets.core import plugins
Access point for initializing and interacting with detection plugins programmatically.
The primary quickstart involves using the command-line interface to create a baseline file. This file (`.secrets.baseline`) tracks existing 'secrets' in your repository, allowing the tool to focus on preventing *new* leaks. The baseline can then be used with pre-commit hooks or CI/CD pipelines.
# 1. Navigate to your repository root.
# 2. Run the scan command to create an initial baseline file.
# This file records all currently detected 'secrets' to be ignored in future scans.
detect-secrets scan > .secrets.baseline
# 3. (Optional) Add to .pre-commit-config.yaml for Git hook integration:
# - repo: https://github.com/bridgecrewio/detect-secrets
# rev: 1.5.47 # Use the current version
# hooks:
# - id: detect-secrets
# args: ['--baseline', '.secrets.baseline']
# 4. To update the baseline with new secrets or remove old ones:
detect-secrets scan --update .secrets.baseline
detect-secrets --version
Debug
Known issues
breakingOlder versions (primarily Yelp's original detect-secrets before version 1.0) changed CLI flag syntax. `--audit` and `--scan` became subcommands `audit` and `scan`. `scan --import <baseline>` became `scan --update <baseline>`. While the `bc-detect-secrets` fork aims for backwards compatibility, awareness of these changes is important if migrating from very old setups or consulting legacy documentation.fixUpdate CLI commands to use subcommands (e.g., `detect-secrets scan` instead of `detect-secrets --scan`) and the `--update` flag for baseline management. Consult the latest documentation for correct syntax.
affects: <1.0 (Yelp/detect-secrets), review for bc-detect-secrets migrations
gotchaBy default, `detect-secrets scan` only operates on files tracked by Git. Untracked files or scanning outside a Git repository will require the `--all-files` flag to be included in the scan command.fixWhen scanning repositories with untracked files or when the repository is not a Git repo, append `--all-files` to your `detect-secrets scan` command.
affects: All versions
gotchaCreating 'slim' baselines using the `--slim` flag will make them incompatible with the `audit` functionality. If you intend to audit your baseline, avoid using the `--slim` option.fixDo not use the `--slim` flag when generating baselines that you intend to audit. If a slim baseline has already been created, it will need to be regenerated without the `--slim` flag to enable auditing.
affects: All versions
gotchaWhen working on Windows, the `.secrets.baseline` file might encounter encoding issues. It is recommended to save this file with UTF-8 with BOM (Byte Order Mark) encoding.fixEnsure your editor saves `.secrets.baseline` files using UTF-8 with BOM encoding to prevent parsing issues.
affects: All versions on Windows
gotchaThis library (`bc-detect-secrets`) is a fork maintained by Bridgecrew of the original `detect-secrets` by Yelp. While aiming for compatibility, users should be aware of this distinction and ensure they are installing the correct package (`bc-detect-secrets`) and referring to the Bridgecrew repository and documentation for the most accurate information.fixVerify that you have installed `bc-detect-secrets` via pip and are consulting the GitHub repository at `github.com/bridgecrewio/detect-secrets` for documentation and issue tracking.
affects: All versions
Errors
Common errors & fixes
detect-secrets: command not found
The `detect-secrets` executable is not in the system's PATH, or the `bc-detect-secrets` package was not installed correctly or its scripts directory is not accessible.
fixEnsure `bc-detect-secrets` is installed globally or in your environment (`pip install bc-detect-secrets`) and that your Python environment's script directory is included in your system's PATH variable.
KeyError: 'JwtTokenDetector'
This error often occurs when an older version of `detect-secrets` (or `bc-detect-secrets`) attempts to process a baseline file generated by a newer version that includes plugins not recognized by the older installation.
fixUpdate your `bc-detect-secrets` installation to the latest version using `pip install --upgrade bc-detect-secrets` to ensure all plugins are available.
Not a valid baseline file!
The baseline file (`.secrets.baseline`) is likely encoded incorrectly, often seen on Windows systems where the default encoding might not be UTF-8.
fixOpen your `.secrets.baseline` file in a text editor and save it with UTF-8 encoding. You might need to regenerate it using `detect-secrets scan > .secrets.baseline` after setting your editor to UTF-8.
AttributeError: type object 'FileType' has no attribute 'JSON'
This specific `AttributeError` indicates a conflict or incompatibility between different versions or forks of `detect-secrets` (e.g., Bridgecrew's `bc-detect-secrets` and Yelp's original `detect-secrets`), especially when both are installed or integrated into other tools like Checkov.
fixIdentify and resolve the conflicting `detect-secrets` installations. If using with tools like Checkov, ensure only one secret scanning framework is active or explicitly disable the conflicting one (e.g., by using `--skip-framework secrets` with Checkov) and run `bc-detect-secrets` separately.
Potential secrets about to be committed to git repo!
The `detect-secrets-hook` is flagging secrets that are already present in your codebase, indicating that they were either not properly added to the baseline, or the baseline itself is not being correctly utilized by the pre-commit hook.
fixFirst, ensure your baseline is up-to-date and correctly audited: `detect-secrets scan > .secrets.baseline` then `detect-secrets audit .secrets.baseline`. If a secret is a false positive or intentional, you can add `pragma: allowlist secret` to the line containing the secret to explicitly ignore it in future scans.
Upgrade
Version history
1.5.50latest on PyPI · released Aug 19, 2026
Audit
Dependencies
diffutilsrequiredRequired system utility for differential scanning on Linux/macOS. May need separate installation on Windows.
jqrequiredRequired system utility for JSON processing on Linux/macOS. May need separate installation on Windows.
word_listoptionalOptional dependency for enhanced secret detection using custom word lists.