TL;DR
- 28.65 million new secrets: Python makes it trivial to hardcode a credential, and 28.65 million new secrets reached public GitHub in 2025.
python-dotenvorkeyringlocally: Load secrets from a.envfile withpython-dotenv, or from the OS keychain withkeyring, and add both to.gitignorebefore the first commit.- Role-based authentication in production: Move to AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault, or HashiCorp Vault, authenticated by role rather than a static key.
SecretStrand thesecretsmodule: Wrap values in Pydantic’sSecretStrso logs and tracebacks cannot print them, and generate tokens with thesecretsmodule rather thanrandom.- 64% still valid after rotation was due: Rotate on a schedule and scan in pre-commit and CI, because more than 64% of the credentials that were valid in 2022 were still valid when retested in January 2026.
Every application you touch in a day, whether it is trading stocks or booking a haircut, is talking to something else behind the scenes, and those conversations are held together by secrets. Python makes it trivial to read a credential from a file and hand it to a client library. That same convenience is why API keys, database passwords, and access tokens keep ending up hardcoded in source code and committed to Git.
GitGuardian detected 28.65 million new hardcoded secrets in public GitHub commits during 2025, a 34% rise year over year and the largest single-year jump on record. Python projects contribute their share, and rarely through carelessness. The fastest path to a working script is usually the least secure one.
In this guide, we will work through six patterns for Python secrets management, each with working code: .env files, JSON config, environment variables, the operating system (OS) keychain, cloud secret managers, and HashiCorp Vault. We will also look at where each pattern fits, how to generate secure tokens with the standard library, and how to keep secrets out of version control in the first place.
What You Need to Follow Along
Before we start, a few things to have in place so nothing trips you up later:
- Python and
pipinstalled - Comfort with Python and a command line interface (CLI)
- An editor or IDE such as VS Code or PyCharm
- A basic understanding of cloud Identity and Access Management (IAM) for the managed options
The shell commands below use macOS and Linux syntax. Windows equivalents are noted where they differ.
Six Ways to Handle Python Secrets Management
n this section, we will go through six patterns, each solving a different problem. These are the secure methods worth knowing, and the first three keep secrets out of source code on a single machine. The last three add encryption at rest, audit trails, and rotation across different environments.
1. Load Secrets From a .env File With python-dotenv
A .env file holds key value pairs that your code reads at startup instead of hardcoding them. It is the standard approach for a local development environment.
Install the python-dotenv package using the following command:
pip install python-dotenv
Now let's create a .env file for testing purposes:
API_KEY=test-key
API_SECRET=test-secret
Of course, this file should never be committed to your Git repo! Add it to your .gitignore before you write a single line of code. Git tracks history, so a committed .env file stays readable even after you delete it.
.env
Already committed it? No worries, it happens. Rotate the credential first, then clean the history using this Git history rewriting cheatsheet. Rotation comes first because history rewriting does not invalidate a secret that someone already copied.
Now read the values. load_dotenv() pushes the file contents into the process environment, where os.getenv can reach them:
from dotenv import load_dotenv
import os
load_dotenv()
api_key = os.getenv("API_KEY")
api_secret = os.getenv("API_SECRET")
One default surprises people. load_dotenv() does not overwrite a variable that already exists in the environment, so an exported value silently wins over the .env file. That is deliberate, because it lets the platform override your local file in production, but it makes for a confusing debugging session when a stale export from last week shadows the value you just edited. Pass override=True when you want the file to take precedence.
The following code snippet uses dotenv_values(), which gives you a dictionary instead and leaves the process environment untouched. That is the safer default when a library you depend on logs its environment:
from dotenv import dotenv_values
secrets = dotenv_values(".env")
def main():
print(secrets["API_KEY"])
if __name__ == "__main__":
main()
Larger projects often need several env files, one per target. You might keep a .env file for local work and a .env.dev file for a cloud development environment:
from dotenv import dotenv_values
secrets = dotenv_values(".env")
dev_secrets = dotenv_values(".env.dev")
Managing secrets this way keeps one file per target, so moving between different environments means loading a different file rather than editing Python code.
Commit a .env.example listing every required variable name with an empty value. New contributors then know what to populate without anyone sharing real credentials over Slack.
2. Read Secrets From a JSON Config File
A JSON file suits nested configuration that a flat env file handles awkwardly. The json file stays out of version control exactly as the .env file does. Let's create a secrets.json file:
{
"db": {
"host": "localhost",
"port": 27017,
"name": "test"
},
"server": {
"host": "localhost",
"port": 3000
}
}
The same rule applies here, so add secrets.json to your .gitignore file immediately. Now that we have the JSON file ready, let's write a small helper to read values out of it:
import json
def get_value_from_json(json_file, key, sub_key):
try:
with open(json_file) as f:
data = json.load(f)
return data[key][sub_key]
except (OSError, KeyError, json.JSONDecodeError) as e:
print("Error: ", e)
return None
print(get_value_from_json("secrets.json", "db", "host"))
Catching specific exceptions rather than a bare Exception keeps a missing key from masking a genuine parse failure.
3. Read Secrets From Environment Variables
Environment variables are set by the operating system, a shell profile, or an orchestrator, and every process inherits them. Because environment variables live outside your code, one script runs unchanged across different environments. Containers and continuous integration (CI) runners rely on this pattern because the platform injects values without touching your code.
Set a variable in macOS or Linux:
export API_KEY_TEST=dummykey
On a Windows machine, the two commands are not interchangeable. set applies to the current Command Prompt session:
set API_KEY_TEST=dummykey
setx writes the variable to the registry so it survives across sessions, but it does not change the window you run it in:
setx API_KEY_TEST "dummykey"
That catches people out. Run setx, then run your script in the same window, and os.environ.get returns None. Open a new terminal afterwards, or use set when you only need the value for the session in front of you.
Read it in your Python script with the os module:
import os
secret_key = os.environ.get("API_KEY_TEST")
Any Python script launched from that shell inherits the value. That is the convenience, and it is also why environment variables leak: every library you import can read them.
Two trade-offs are worth stating plainly. Exporting a secret on the command line writes it to your shell history, so prefer a .env file or your secrets manager's CLI for interactive work. Environment variables are also visible to every child process and often to anything that dumps process state, which makes them a weak fit for long-lived, high-value credentials. Secrets at the command line deserve special care too, and GitGuardian has a fuller breakdown of secrets at the command line.
4. Store Secrets in the OS Keychain With Python Keyring
The keyring package stores credentials in the operating system's own credential store rather than a file on disk. On macOS that is Keychain, on Windows it is Credential Locker, and on Linux it is any Secret Service provider such as GNOME Keyring or KWallet. Nothing sits in plaintext in your project directory, so there is no file to commit by accident.
pip install keyring
Use it to store secrets for a CLI tool and to access secrets again on the next run without a prompt. The API is three functions, which is the whole appeal:
import keyring
keyring.set_password("my-app", "api_user", "s3cr3t-value")
api_key = keyring.get_password("my-app", "api_user")
keyring.delete_password("my-app", "api_user")
This is a strong option for developer workstations and CLI tools, and a poor one for servers. A headless Linux box has no Secret Service running by default, so keyring either fails or falls back to a less protected backend. Be honest about the threat model too: keyring protects secrets at rest and keeps them out of Git, but any process running as your user can request them. It is not a defense against malware that already executes on the machine, and secrets accumulate on developer machines in more places than the keychain.
5. Retrieve Secrets From a Cloud Secrets Manager
Every major provider offers a managed secrets manager with encryption at rest, IAM-scoped access, audit logging, and automated rotation. This is the point where secrets handling becomes a cloud security concern rather than a local convention. Pick the one matching your cloud environment, or compare the wider field of secrets management tools:
In all three cases, authenticate with an attached role or workload identity rather than a static access key. Otherwise you have simply moved the problem: you now need a secret to fetch your secrets.
Let's write a small retrieval function for each of the three.
AWS Secrets Manager with the boto3 Python client. There is also a deeper guide to handling secrets with AWS Secrets Manager:
import boto3
def fetch_secret_from_aws(secret_name, region="us-east-1"):
client = boto3.session.Session().client("secretsmanager", region_name=region)
return client.get_secret_value(SecretId=secret_name)["SecretString"]
Google Cloud Secret Manager, often written GCP Secret Manager, with the google-cloud-secret-manager library. Versioning is explicit, so the version is a required argument here rather than defaulting to latest. Pass a specific version number in production and reserve the string latest for local work:
from google.cloud import secretmanager
def fetch_secret_from_gcp(project_id, secret_id, version):
client = secretmanager.SecretManagerServiceClient()
name = f"projects/{project_id}/secrets/{secret_id}/versions/{version}"
response = client.access_secret_version(request={"name": name})
return response.payload.data.decode("UTF-8")
Azure Key Vault with azure-keyvault-secrets and azure-identity. DefaultAzureCredential resolves a managed identity in Azure and your local login during development, so the same code runs in both places:
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
def fetch_secret_from_azure(vault_url, secret_name):
client = SecretClient(vault_url=vault_url, credential=DefaultAzureCredential())
return client.get_secret(secret_name).value
AWS Secrets Manager, Azure Key Vault, and Google Cloud Secret Manager expose the same shape of API: authenticate, name the secret, retrieve secrets at runtime. Cloud providers differ mainly in how they scope access to authorized users and how they version values, so the switching cost between them stays low. All three beat an env file for anything holding production access.
Each call crosses the network, so cache the result in memory for the process lifetime instead of fetching per request. Cache with a short expiry if you rely on rotation.
6. Centralize Secrets With HashiCorp Vault
HashiCorp Vault is a secrets manager rather than a key management system, though the two often get conflated. A key management system such as AWS KMS or Google Cloud KMS manages cryptographic keys and performs encryption operations. Vault stores and issues secrets, and can generate short-lived database credentials on demand. Teams reach for it across cloud platforms and on premises when they want one control plane instead of three.
Install the hvac Python client, make sure you have a Vault instance to talk to, then let's write two functions: one to read a secret from a path, and one to write one back.
import hvac
def read_secret_from_vault(secret_path, token, secret_name):
client = hvac.Client(url="http://localhost:8200", token=token)
response = client.secrets.kv.v2.read_secret_version(
path=secret_path,
raise_on_deleted_version=True,
)
return response["data"]["data"][secret_name]
def write_secret_to_vault(secret_path, token, secret_name, secret_value):
client = hvac.Client(url="http://localhost:8200", token=token)
return client.secrets.kv.v2.create_or_update_secret(
path=secret_path,
secret={secret_name: secret_value},
)
Set raise_on_deleted_version explicitly. Omitting it emits a deprecation warning on current hvac releases, and the default is scheduled to flip from true to false in hvac 3.0, which would quietly turn a deleted secret version into a successful call returning no data.
Vault's dynamic secrets engine is the feature that justifies the operational cost. Instead of one database password shared by every service for two years, each service leases a credential that expires in an hour.
What Counts as a Secret in Python
A secret is any value that grants access to something. Secret keys, API keys, database passwords, OAuth tokens, and connection strings all qualify. A port number or a log level does not.
The distinction matters because it decides where a value lives. Configuration can sit in a committed file. Secrets cannot, because anyone who reads them can gain unauthorized access to the systems behind them. Malicious actors scan public repositories continuously for exactly this kind of sensitive information.
Leaked secrets rarely travel by one route. They surface in version control systems, private messages, ticket comments, build logs, and support attachments, which is why sensitive data belongs outside your Python code from the start.
One naming collision trips up almost everyone new to this topic. Python ships a standard library module called secrets, but it does not store credentials. It generates cryptographically strong random values. Storing and retrieving secrets is handled by the six patterns above; generating them is handled by that module, which has its own section further down.
Typed Configuration With Pydantic Settings and SecretStr
Most of the patterns above return strings, which means a typo surfaces at runtime and a stray print() or traceback can leak the value straight into your logs. Pydantic Settings solves both problems.
pip install pydantic-settings
Now let's declare the configuration as a class. Pydantic reads from the process environment and your .env file, validates types, and fails fast on a missing variable name:
from pydantic import SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_file=".env")
api_key: SecretStr
database_url: SecretStr
region: str = "us-east-1"
settings = Settings()
print(settings.api_key)
print(settings.api_key.get_secret_value())
Pydantic reads your Python environment as well, so one Settings class covers a .env file locally and injected environment variables in production.
SecretStr is the part that matters for secure storage in memory. Printing the field or logging the object renders a masked string, and the real value only appears when you call get_secret_value() explicitly. Accidental exposure through logs, error trackers, and debug output is one of the most common leak paths in Python applications, and this closes it by default.
Generate Secure Tokens With the Python Secrets Module
The secrets module, added in Python 3.6, draws on the operating system's cryptographically secure randomness source. The random module does not: it is a deterministic pseudo-random generator built for simulation, and an attacker who observes enough output can predict the rest. Use secrets for anything that acts as a credential.
import secrets
api_token = secrets.token_urlsafe(32)
session_id = secrets.token_hex(16)
pick = secrets.choice("abcdefghijklmnopqrstuvwxyz")
token_bytes() returns raw bytes, token_hex() returns a hexadecimal string, and token_urlsafe() returns URL-safe Base64. secrets.choice() and secrets.randbelow() cover secure selection. On token length, the documentation notes that 32 bytes, or 256 bits, of randomness is considered sufficient for the module's typical use case, and points out that what counts as sufficient rises as hardware gets faster.
Rotate, Compare, and Clear Secrets Safely
Generating and storing a secret is the start. Three habits matter for the rest of its life.
Compare in constant time. A normal == comparison returns as soon as it finds a mismatched byte, and that timing difference leaks information about the expected value. Use compare_digest() whenever you validate an incoming API key or token:
import secrets
def validate_api_key(provided_key, stored_key):
return secrets.compare_digest(provided_key, stored_key)
Both arguments have to be the same type, and str values must be ASCII only, so normalize at the boundary. Comparing a bytes value pulled from a request header against a str loaded from config raises a TypeError rather than returning False, which is an easy way to turn an auth check into a 500.
Rotate on a schedule, and immediately after any exposure. Long-lived credentials are the reason old leaks still matter. Of the credentials GitGuardian confirmed as valid in 2022, more than 64% were still valid when the same dataset was retested in January 2026, down only marginally from nearly 70% a year earlier (State of Secrets Sprawl 2026). Cloud secret managers and Vault automate this. If you are on .env files, rotation is a manual calendar item, which is a reason to graduate off them.
Limit a secret's lifetime in memory. Python strings are immutable and garbage collected on their own schedule, so you cannot reliably zero one out. Keep secrets in narrow scopes, avoid building them through string concatenation, and prefer bytearray when you genuinely need to overwrite bytes. Attack vectors here are subtle: a heap dump, a crash report, or a stray log line can expose sensitive information long after the request finished. For the highest-value keys, keep the material in a hardware security module or a KMS and send data to it rather than pulling keys out.
Handle Secrets Safely in Jupyter Notebooks
Notebooks are the easiest place in the Python ecosystem to leak a credential, because the output of every cell is saved into the .ipynb file alongside the code. A key pasted into a cell gets committed twice: once as source, once as output. So never paste one into a cell at all.
Use getpass to prompt instead:
from getpass import getpass
import os
os.environ["API_KEY"] = getpass("API key: ")
Better still, load from .env or your secrets manager exactly as you would in a script. Clear all outputs before committing, and add .ipynb_checkpoints/ to .gitignore.
AI coding assistants raise the stakes here. GitGuardian measured a 3.2% secret-leak rate in Claude Code-assisted commits during 2025, against a 1.5% baseline across all public GitHub commits, and an assistant with access to your notebook can copy a pasted key into a prompt, a log, or a suggested commit. GitGuardian covers local guardrails for secrets security in more depth.
How GitGuardian Helps You Keep Python Secrets Out of Version Control
Every pattern above depends on one thing holding: the secret file never reaches your repository. .gitignore is necessary and not sufficient, because it does nothing about a secret pasted directly into a .py file, a notebook output, or a test fixture. Those are the paths most accidental exposure takes.
Secure management does not end at storage. Managing secrets at scale means assuming a mistake will happen and catching it automatically. GitGuardian closes that gap at three points in a Python workflow:
- Before the commit:
ggshield, GitGuardian's CLI, runs as a pre-commit hook and blocks the commit while the credential is still only on your machine, so it never enters history and never needs a rewrite. - In the pipeline: the same scan runs in continuous integration as a backstop for anything committed without the hook installed, which covers new contributors and machines you do not control.
- Across your repositories: Internal Secrets Monitoring scans full Git history, checks whether each detected credential is still live, and routes it to an owner with remediation steps attached. Public Secrets Monitoring does the same for credentials that reach public GitHub through a fork or a personal account.
Getting the pre-commit hook running takes three commands:
pip install ggshield
ggshield auth login
ggshield secret scan pre-commit
The detection engine ships with more than 500 purpose-built detectors, and the GitGuardian app is the most installed security application on the GitHub Marketplace.
This complements your secrets manager rather than replacing it. The manager decides where credentials live and who can read them. Scanning verifies that none of them leaked along the way. Those are different questions, and a Python codebase needs answers to both.
Pipelines deserve the same attention as source files, since a leaked continuous integration credential usually carries broader access than a developer's. The OWASP Top 10 CI/CD security risks map where those failures happen.
A Python Secrets Management Checklist
Managing Python secrets well comes down to a handful of habits.
- Avoid hardcoding secrets in source code. Load them at runtime from a file, the environment, the keychain, or a secrets manager.
- Add
.env,secrets.json, and.ipynb_checkpoints/to.gitignorein the first commit, and ship a.env.examplefor contributors. - Use
.envandkeyringlocally. Use a cloud secrets manager or Vault for production workloads, authenticated by role rather than a static key. - Wrap credentials in
SecretStrso logs and tracebacks cannot print them. - Generate tokens with
secrets, neverrandom, and validate them withcompare_digest(). - Prefer platform-injected environment variables over committed files in production.
- Rotate on a schedule, and treat any exposure as a rotation event rather than a cleanup task.
- Run secrets scanning in pre-commit and in CI, because the file you forgot to ignore is the one that leaks.
Secure management of Python secrets is less about picking the perfect tool than about making the secure path the easy one. Most accidental exposure traces back to a missing .gitignore entry or a value pasted into a file for a quick test. A .env file with a matching ignore rule and a pre-commit hook takes ten minutes to set up and removes the most common failure mode entirely.
If you prefer to keep encrypted secrets in the repository and share them with your team, Mozilla SOPS is a flexible alternative worth reading about. This post is also part of a series covering secrets in Docker, AWS secrets, and secrets in Jenkins.
FAQ
What is the difference between secrets and environment variables?
A secret is the sensitive value itself, such as an API key or database password. An environment variable is one delivery mechanism for it. You can pass a secret through an environment variable, but the variable offers no encryption, no audit log, and no rotation, so it is transport rather than secure storage. Treat the secret as sensitive information and the variable as a pipe.
Is dotenv needed anymore?
Yes, for local development. Running pip install python-dotenv is usually the first line of a Python project's setup notes, and python-dotenv loads a .env file into your local environment so one code path works locally and in production, where the platform injects environment variables directly. It is not built for production secret management, since a .env file is unencrypted and unaudited.
Is Python keyring safe?
It is safer than a plaintext file and appropriate for workstations and CLI tools. Keyring delegates storage to the OS credential store, which encrypts secrets at rest and keeps them out of your project directory. It does not protect against malware already running as your user, and it is a weak fit for headless servers.
What is the purpose of keyring in Linux?
On Linux, keyring talks to a Secret Service provider such as GNOME Keyring or KWallet, which stores credentials encrypted and unlocks them with your login session. Desktop applications use it so users are not prompted for passwords repeatedly. Headless servers usually have no provider installed.
Is Python secrets safe?
Yes, for generating credentials. The secrets module pulls from the operating system's cryptographically secure randomness source, which makes it suitable for tokens, session keys, and passwords. Note that it generates secrets and does not store them; storage needs a file, keychain, or secrets manager.
Why don't we push .env files?
Because Git keeps history. Once a .env file is committed, the credential stays readable to anyone with repository access even after you delete the file, and it becomes public the moment the repository does. Add .env to .gitignore before the first commit and share a .env.example instead.
What are best practices for handling secrets in Jupyter notebooks?
Never paste a secret into a cell, because notebooks save cell output into the .ipynb file. Prompt with getpass, or load from .env or a secrets manager. Clear all outputs before committing, add .ipynb_checkpoints/ to .gitignore, and apply IAM policies on managed notebook services.
How can I use Python to detect secrets?
Run a secrets scanner over your repository and wire it into a pre-commit hook so it blocks a commit before the credential enters history, then run the same scan in CI. Pattern matching alone produces heavy false positives, so choose a scanner that validates whether a detected credential is still live. Pair it with the secure methods above rather than treating it as a substitute for them.
This article is a guest post. Views and opinions expressed in this publication are solely those of the author and do not reflect the official policy, position, or views of GitGuardian, The content is provided for informational purposes, GitGuardian assumes no responsibility for any errors, omissions, or outcomes resulting from the use of this information. Should you have any enquiry with regard to the content, please contact the author directly.

