Install & Compatibility
Where this runs
tested against v1.0.16 · 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.920 runs
installs and imports cleanly · install 0.0s · import 1.202s · 54.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.4s · import 1.082s · 55MB
54MB installed
● package 54MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
InfisicalSDKClient
✓ from infisical_sdk import InfisicalSDKClient
InfisicalClient
✓ This import is for an older, deprecated SDK.
✗ from infisical import InfisicalClient
This import path refers to a previous, now legacy, Python SDK ('infisical' package) which is no longer actively maintained. For new projects and upgrades, use `from infisical_sdk import InfisicalSDKClient`.
This quickstart demonstrates how to initialize the `InfisicalSDKClient` and fetch secrets. It shows how to retrieve a single secret by name and how to list all secrets within a specified project, environment, and path. Authentication can be done via a direct service token or through Machine Identity credentials (e.g., Universal Auth).
import os
from infisical_sdk import InfisicalSDKClient
from infisical_sdk.models.shared import UniversalAuthLoginInput
# It's recommended to use environment variables for sensitive data like tokens
# For Universal Auth, you would typically use INFISICAL_UNIVERSAL_AUTH_CLIENT_ID and INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET
# Or a service token directly via INFISICAL_TOKEN
# For this example, we'll use a direct token, but env vars are preferred.
INFISICAL_TOKEN = os.environ.get('INFISICAL_TOKEN', 'your_infisical_service_token') # Replace with your actual token or set as env var
INFISICAL_PROJECT_ID = os.environ.get('INFISICAL_PROJECT_ID', 'your_project_id') # Replace with your project ID or set as env var
INFISICAL_ENVIRONMENT = os.environ.get('INFISICAL_ENVIRONMENT', 'dev') # Replace with your environment or set as env var
try:
# Initialize the client. The 'token' parameter allows direct authentication.
# Alternatively, you can use client.auth.universal_auth.login() with client_id/client_secret.
client = InfisicalSDKClient(token=INFISICAL_TOKEN)
# Fetch a single secret by its name
secret = client.secrets.get_secret_by_name(
secret_name='MY_APPLICATION_SECRET',
project_id=INFISICAL_PROJECT_ID,
environment_slug=INFISICAL_ENVIRONMENT,
secret_path='/'
)
if secret and hasattr(secret, 'secret_value'):
print(f"Fetched secret 'MY_APPLICATION_SECRET': {secret.secret_value}")
else:
print("Secret 'MY_APPLICATION_SECRET' not found or has no value.")
# List all secrets in a specific path and environment
all_secrets_response = client.secrets.list_secrets(
project_id=INFISICAL_PROJECT_ID,
environment_slug=INFISICAL_ENVIRONMENT,
secret_path='/'
)
if all_secrets_response and all_secrets_response.secrets:
print("\nAll secrets in root path:")
for s in all_secrets_response.secrets:
print(f" - {s.secret_name}: {s.secret_value}")
else:
print("No secrets found in the specified path.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingBreaking changes were introduced in version 1.0.3 related to API response structures and property naming. The `rest` attribute was removed, new response types like `BaseSecret` are used, and some properties (e.g., `secret_key`) were renamed to `secretKey`.fixUpgrade to `infisicalsdk` version 1.0.3 or higher and update your code to reflect the new response object types and property names as per the official documentation. You may need to import `BaseSecret` and other response types from `infisical_sdk.models.shared`.
affects: < 1.0.3
gotchaSpecific authentication methods like OIDC Auth, Token Auth, and LDAP Auth require minimum SDK versions to function correctly. Using these methods with older SDK versions will result in errors.fixEnsure you are using `infisicalsdk` version 1.0.10 or newer for OIDC Auth, 1.0.13 or newer for Token Auth, and 1.0.16 or newer for LDAP Auth. Always update to the latest SDK version to access the newest authentication capabilities and bug fixes.
affects: < 1.0.10 (OIDC), < 1.0.13 (Token), < 1.0.16 (LDAP)
gotchaThe `list_secrets` method's `attach_to_os_environ` parameter defaults to `False`. This means secrets fetched will *not* automatically be set as environment variables in your Python process unless explicitly specified.fixIf you intend for fetched secrets to be accessible via `os.environ`, you must explicitly set `attach_to_os_environ=True` when calling `list_secrets`.
affects: All versions
gotchaHardcoding Infisical Machine Identity Tokens or other sensitive credentials directly in your code is a security risk and is strongly discouraged.fixStore Infisical tokens and other sensitive information in environment variables (e.g., `INFISICAL_TOKEN`, `INFISICAL_UNIVERSAL_AUTH_CLIENT_ID`, `INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET`) and retrieve them using `os.environ.get()` at runtime. Infisical also supports more secure authentication mechanisms like Universal Auth via Machine Identities.
affects: All versions
gotchaA `thread leak` issue was fixed in version 1.0.15. Older versions might suffer from resource exhaustion in long-running applications.fixUpgrade to `infisicalsdk` version 1.0.15 or newer to benefit from the thread leak fix and improve application stability, especially in concurrent or long-running environments.
affects: < 1.0.15
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'infisical_sdk'
The 'infisicalsdk' Python package has not been installed in the current environment.
fixInstall the package using pip: `pip install infisicalsdk`
infisical_sdk.InfisicalException: Unauthorized: Invalid client_id or client_secret provided
The `clientId` or `clientSecret` passed to the `client.auth.universal_auth.login()` method are incorrect, expired, or the associated machine identity lacks the necessary permissions on the Infisical platform.
fixDouble-check your Machine Identity's `clientId` and `clientSecret` in your Infisical dashboard and ensure it has appropriate access policies for the project and environment you are trying to access.
infisical_sdk.InfisicalException: Bad Request: Missing required parameter: projectId or environment
When calling secret retrieval methods like `client.secrets.get()` or `client.secrets.list()`, a mandatory parameter such as `projectId` or `environment` was either not provided or was empty.
fixEnsure that all required parameters like `secret_name`, `projectId`, and `environment` are correctly passed to the secret retrieval methods. Example: `client.secrets.get(secret_name="MY_SECRET", project_id="<your-project-id>", environment="dev")`
requests.exceptions.ConnectionError: HTTPSConnectionPool(host='<infisical_host>', port=443): Max retries exceeded with url: /api/v3/secrets...
The `infisicalsdk` client could not establish a connection to the Infisical host URL, likely due to network issues, an incorrect `host` URL specified during client initialization, or the Infisical server being unreachable or down.
fixVerify that the `host` URL provided when initializing `InfisicalSDKClient` is correct and accessible from your application's environment. Check network connectivity and ensure the Infisical server is running.
Upgrade
Version history
1.0.16latest on PyPI · released Feb 18, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.7 or newer.