---
id: ggshield
version: "1.53.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# ggshield — Detect secrets from all sources using GitGuardian's brains

License: permissive · Maintenance: active · Downloads: 513.1K/mo

## What it is and what it does

ggshield is a command-line security scanner that integrates with GitGuardian's threat detection API to find secrets and vulnerabilities in your codebase. It runs locally or in CI/CD pipelines and can scan files, Git repositories, Docker images, and PyPI packages. The tool sends only metadata (call time, request size, scan mode) to GitGuardian—your actual files and secrets remain local and are not stored on their servers. You authenticate once with a personal access token, then use simple commands like `ggshield secret scan path` to check directories or `ggshield secret scan repo` to scan a repository. It's designed to catch credential leaks before they reach version control, supporting integration as Git hooks (pre-commit, pre-push, pre-receive) and CI/CD workflows.

The package depends on 24 runtime libraries including click for CLI handling, cryptography and pyjwt for authentication, requests and oauthlib for API communication, and rich for terminal output formatting. It requires a non-EOL Python version (3.9 or later) and git. The tool is actively maintained, with recent releases and ongoing repository updates, making it suitable for teams implementing secrets detection as part of their development security workflow.

Use it for:

- Prevent accidental commits of API keys, database passwords, or OAuth tokens to Git repositories.
- Scan Docker images before deployment to detect embedded credentials or secrets in layers.
- Integrate into CI/CD pipelines to block builds or pull requests containing detected secrets.
- Set up pre-commit Git hooks to catch secrets locally before they reach the repository.
- Audit PyPI packages for embedded credentials or leaked secrets in dependencies.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

ggshield is a CLI tool that scans files, repositories, Docker images, and PyPI packages to detect more than 500+ types of secrets and potential vulnerabilities using GitGuardian's API.

Yes. ggshield is actively maintained, has low installation friction, carries a permissive MIT license, and solves a critical security problem (preventing secrets in code). It integrates cleanly into development workflows via Git hooks or CI/CD, requires no complex setup beyond authentication, and has no known vulnerabilities. Install it if your team needs automated secrets detection.

## Install

pip install ggshield
uv add ggshield
poetry add ggshield

## Installing ggshield

Before you install: Low friction installation with a pure Python wheel and 24 runtime dependencies. Active maintenance with a recent release 17 days ago and ongoing repository activity. Supports current Python versions (3.9–3.13) and follows the Python release cycle.

License in practice: MIT license (permissive) means you can use, modify, and distribute ggshield freely in commercial and private projects with minimal restrictions, provided you include the license notice.

Quickstart:

pipx install ggshield
ggshield auth login
ggshield secret scan path -r .

Requires a supported (non-EOL) version of Python and git. Authentication via GitGuardian API key (GITGUARDIAN_API_KEY environment variable or interactive login) is required before scanning.

Verify before relying:

- Whether the '500+ types of secrets' detection claim is current and what categories are covered.
- Performance characteristics and scan time for large repositories or Docker images.
- Whether pre-commit hook integration is automatic or requires manual configuration.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 513.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

secret detection cli, secrets scanner, credential leak detection, gitguardian secrets, devsecops scanning tool, pre-commit secret scanning, ci/cd secret detection, devsecops, secrets-detection, pre-commit-hook

[View on SkillFed](https://skillfed.io/packages/ggshield) · [View on PyPI](https://pypi.org/project/ggshield/)