Install & Compatibility
Where this runs
tested against v1.12.10 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.754s · 55.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.2s · import 0.668s · 56MB
55MB installed
● package 55MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Salesforce
✓ from simple_salesforce import Salesforce
The primary class for interacting with the Salesforce API.
SalesforceLogin
✓ from simple_salesforce.api import SalesforceLogin
A helper function for more granular control over the login process, though 'Salesforce' constructor handles most cases.
This quickstart demonstrates how to authenticate with Salesforce using username, password, and security token, then perform a simple SOQL query, create an account, and delete it. It emphasizes using environment variables for sensitive credentials.
import os
from simple_salesforce import Salesforce
# It's highly recommended to use environment variables for credentials
USERNAME = os.environ.get('SF_USERNAME', 'your_username@example.com')
PASSWORD = os.environ.get('SF_PASSWORD', 'your_password')
SECURITY_TOKEN = os.environ.get('SF_SECURITY_TOKEN', 'your_security_token')
# Optional: for sandbox use domain='test'
# For specific API versions, use sf_version='X.Y'
try:
sf = Salesforce(
username=USERNAME,
password=PASSWORD,
security_token=SECURITY_TOKEN,
# domain='test' # Uncomment for sandbox
# sf_version='59.0' # Uncomment for a specific API version
)
print(f"Successfully connected to Salesforce instance: {sf.instance_url}")
# Example: Query Account records
query_result = sf.query("SELECT Id, Name FROM Account LIMIT 5")
print("\nFirst 5 Account Names:")
for record in query_result['records']:
print(f" - {record['Name']} (Id: {record['Id']})")
# Example: Create a new Account (replace with unique name for testing)
new_account_name = "Test Account from simple-salesforce_" + str(os.urandom(4).hex())
new_account = {'Name': new_account_name}
create_result = sf.Account.create(new_account)
print(f"\nCreated Account: {new_account_name} with Id: {create_result['id']}")
# Example: Delete the created Account (cleanup)
delete_result = sf.Account.delete(create_result['id'])
print(f"Deleted Account with Id: {create_result['id']}")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure your SF_USERNAME, SF_PASSWORD, and SF_SECURITY_TOKEN environment variables are set correctly.")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'simple_salesforce'
This error occurs when the 'simple-salesforce' library is not installed, or the import statement uses an incorrect module name (e.g., 'salesforce' instead of 'simple_salesforce').
fixEnsure the library is installed using `pip install simple-salesforce` and imported as `from simple_salesforce import Salesforce`.
SalesforceAuthenticationFailed: invalid_grant: authentication failure
This error means the provided Salesforce username, password, or security token is incorrect, or IP restrictions are preventing access.
fixVerify all credentials are correct, ensure the security token is appended directly to the password if required, and check for any IP restrictions or login hour policies on the Salesforce side.
SalesforceError: [StatusCode: 404] NOT_FOUND
This indicates that the Salesforce object, field, or record you are trying to access or manipulate does not exist, or your user profile lacks permissions to see it.
fixDouble-check the API name of the object/field/record ID for typos, and ensure the authenticated user has appropriate read/write permissions for that resource in Salesforce.
SalesforceError: [StatusCode: 500] INVALID_SESSION_ID: Session ID not found, please login again.
The current Salesforce session has expired due to inactivity or invalidation, requiring re-authentication to obtain a new valid session.
fixRe-establish the Salesforce connection by re-instantiating the `Salesforce` object with your credentials to generate a fresh, valid session ID.
AttributeError: 'Salesforce' object has no attribute 'query_all'
This error typically means you've misspelled a method name or an object's API name, or are attempting to access a non-existent attribute of the `Salesforce` connection object.
fixCorrect the method or object name to match `simple-salesforce`'s conventions or Salesforce's API names (e.g., `sf.query_all()` for queries or `sf.Contact.get()` for object methods).
Upgrade
Version history
1.12.10latest on PyPI · released Jul 8, 2026
Audit
Dependencies
requestsrequiredUsed for all HTTP communication with the Salesforce API.
python-dotenvoptionalCommonly used in quickstart examples for managing credentials securely via environment variables.