Registry / auth-security / pygitguardian

pygitguardian

JSON →
library1.30.0pypypi✓ verified 87d ago

pygitguardian is the official Python client library for the GitGuardian API, allowing developers to detect over 200 types of secrets and other security vulnerabilities in text content. It is actively developed with frequent releases, currently at version 1.29.0.

pip install pygitguardian
INSTALL
IMPORT
SIG · PYGITGUARDIAN
P
pygitguardian
auth-securitypythonv1.30.0
Install
2.8s avg
Import
911ms
Disk
25MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.30.0 · 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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.966s · 23.2MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.8s · import 0.856s · 24MB
25MB installed
● package 25MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

GGClient
from pygitguardian import GGClient
The primary client for interacting with the GitGuardian API.
Detail
from pygitguardian.models import Detail
A model used for handling API response details, such as error messages.

Initializes the GGClient with an API key sourced from an environment variable and performs a content scan for secrets. It includes a health check and prints detected incidents. API keys should always be handled securely, ideally via environment variables, to prevent exposure.

import os from pygitguardian import GGClient from pygitguardian.models import ScanResult # It is highly recommended to use environment variables for API keys. # Replace 'YOUR_GITGUARDIAN_API_KEY' with your actual environment variable name if different. api_key = os.environ.get('GITGUARDIAN_API_KEY', '') if not api_key: print("Error: GITGUARDIAN_API_KEY environment variable not set.") exit(1) client = GGClient(api_key=api_key) document_to_scan = """ This is some example content. It might contain sensitive information like a password: mysecretpassword123 or an API key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx """ try: # Check the health of the API and the API key used first health_check_result = client.health_check() if not health_check_result.success: print(f"API Health Check failed: {health_check_result.detail}") exit(1) print("API Health Check successful.") scan_result: ScanResult = client.content_scan(document_to_scan) if scan_result.has_secrets: print("Secrets found in the document!") for incident in scan_result.incidents: print(f" Incident type: {incident.type}") for pb in incident.policy_breaks: print(f" Policy Break: {pb.occurrence.value}") else: print("No secrets found in the document.") except Exception as e: print(f"An error occurred during scan: {e}")
Debug
Known issues
breakingVersion 1.20.0 removed support for the deprecated SCA (Software Composition Analysis) and IaC (Infrastructure as Code) scanning endpoints.
fix
Migrate any code using these deprecated endpoints to alternative GitGuardian API methods or tools, or ensure your application does not rely on these specific functionalities.
affects: >=1.20.0
breakingVersion 1.25.0 updated the `Client.scan_and_create_incidents()` method to align with server-side API changes. This may require reviewing and updating parameters or expected behavior if this method was previously used.
fix
Consult the latest pygitguardian documentation or examples for `scan_and_create_incidents()` to ensure correct usage with the updated API.
affects: >=1.25.0
gotchaIn version 1.27.0, several fields including `visibility`, `kind`, `presence status`, `ignore_reason`, and `tag` were changed to `str` type. Code expecting different types (e.g., enums or custom objects) might encounter type errors.
fix
Update type hints and any logic that processes these fields to expect string values. Perform explicit type conversions if a non-string type is required by your application.
affects: >=1.27.0
gotchaAs of version 1.23.0, the `detector_name` and `detector_group_name` fields in `PolicyBreak` objects were made optional. Code expecting these fields to always be present should implement checks for `None`.
fix
Before accessing `policy_break.detector_name` or `policy_break.detector_group_name`, check if the value is `None` to prevent `AttributeError` or unexpected behavior.
affects: >=1.23.0
Errors
Common errors & fixes
Invalid API Key
The `pygitguardian` client was initialized with an invalid, expired, or missing GitGuardian API key, leading to authentication failure.
fix
Ensure your GitGuardian API key is correctly set as the `GITGUARDIAN_API_KEY` environment variable or passed directly to the `GGClient` constructor. You can verify the key's validity using `client.health_check()`.
ModuleNotFoundError: No module named 'pygitguardian'
The `pygitguardian` library is not installed in the current Python environment, or the import statement is incorrect.
fix
Install the library using pip: `pip install pygitguardian` or `pip3 install --upgrade pygitguardian`.
status code 429
The application has exceeded the GitGuardian API rate limits or its allocated monthly quota.
fix
Reduce the frequency of API calls, implement retry logic with exponential backoff, or contact GitGuardian support to discuss increasing your API quota limits.
Upgrade
Version history
1.30.0latest on PyPI · released Apr 28, 2026
Audit
Dependencies
requestsrequiredHTTP client for making API requests.
marshmallowrequiredUsed for request (de)serialization and input validation.
Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources
pygitguardian — pip install pygitguardian · libregistry