Install & Compatibility
Where this runs
tested against v4.11.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.388s · 21.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.362s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Connection
✓ from swiftclient.client import Connection
✗ import swiftclient.client
Directly import the Connection class for the low-level API.
SwiftService
✓ from swiftclient.service import SwiftService
✗ import swiftclient.service
Directly import the SwiftService class for the high-level API.
This quickstart demonstrates how to establish a connection to OpenStack Swift using the low-level `Connection` API, authenticate, list existing containers, create a new container, and upload an object. It relies on standard OpenStack environment variables for authentication details to avoid hardcoding credentials.
import os
from swiftclient.client import Connection
# --- Environment Variables for Authentication ---
# Set these environment variables before running, e.g., using an OpenStack RC file
# or directly:
# export OS_AUTH_URL="http://your-auth-url:5000/v3"
# export OS_USERNAME="your-username"
# export OS_PASSWORD="your-password"
# export OS_PROJECT_NAME="your-project-name"
# export OS_USER_DOMAIN_NAME="Default" # Or your specific user domain
# export OS_PROJECT_DOMAIN_NAME="Default" # Or your specific project domain
# export OS_REGION_NAME="RegionOne" # Or your specific region
auth_url = os.environ.get('OS_AUTH_URL', 'http://localhost:5000/v3')
username = os.environ.get('OS_USERNAME', 'test_user')
password = os.environ.get('OS_PASSWORD', 'test_password')
project_name = os.environ.get('OS_PROJECT_NAME', 'test_project')
user_domain_name = os.environ.get('OS_USER_DOMAIN_NAME', 'Default')
project_domain_name = os.environ.get('OS_PROJECT_DOMAIN_NAME', 'Default')
region_name = os.environ.get('OS_REGION_NAME', 'RegionOne')
# Ensure auth_version is specified, especially for Keystone v3
# os_options are crucial for domain-scoped authentication
os_options = {
'user_domain_name': user_domain_name,
'project_domain_name': project_domain_name,
'project_name': project_name,
'region_name': region_name
}
try:
# Establish connection
conn = Connection(
authurl=auth_url,
user=username,
key=password,
os_options=os_options,
auth_version='3' # Crucial: always specify auth_version for v3 or v2 auth
)
# Example: List containers
_resp_headers, containers = conn.get_account()
print(f"Successfully connected. Found {len(containers)} containers:")
for container in containers:
print(f" - {container['name']} (Bytes: {container['bytes']}, Count: {container['count']})")
# Example: Create a new container
container_name = "my-new-test-container"
try:
conn.put_container(container_name)
print(f"Container '{container_name}' created (or already exists).")
except Exception as e:
print(f"Error creating container {container_name}: {e}")
# Example: Upload an object (simple string content)
object_name = "hello_world.txt"
object_content = b"Hello, Swift Object Storage!"
try:
conn.put_object(container_name, object_name, object_content)
print(f"Object '{object_name}' uploaded to '{container_name}'.")
except Exception as e:
print(f"Error uploading object {object_name}: {e}")
finally:
# Always close the connection
if 'conn' in locals():
conn.close()
print("Connection closed.")
swift --version
Debug
Known issues
gotchaWhen using `swiftclient.client.Connection`, always explicitly specify the `auth_version` parameter (e.g., '2.0' or '3'). Omitting it can cause authentication failures as it defaults to '1.0', which may not be compatible with modern OpenStack Keystone deployments.fixPass `auth_version='3'` (or '2.0') to the `Connection` constructor, and ensure `authurl` is correctly formatted for the specified version (e.g., includes `/v3` for Keystone v3).
affects: All versions, particularly when interacting with non-v1 auth endpoints.
breakingSupport for Python 3.6 was dropped in version 4.8.0. Earlier, support for Python 2 was completely removed.fixUpgrade to Python 3.7 or newer to use python-swiftclient versions >= 4.8.0. For older python-swiftclient versions, ensure Python 3.x is used.
affects: 4.8.0 and later (Python 3.6), all versions (Python 2)
deprecatedThe provider-specific `SERVICENET` feature was removed in version 4.10.0. If your deployment relied on this, you will need to manually override your storage URLs.fixExplicitly configure the storage URLs in your client configuration or environment variables, rather than relying on `SERVICENET`.
affects: 4.10.0
gotchaDebugging output (e.g., using `--debug` with the CLI or setting logging to DEBUG) truncates authentication tokens by default since version 4.8.0 for security reasons.fixIf full authentication token details are absolutely necessary for debugging, use the `--debug-with-secrets` flag (CLI) or ensure your logging configuration explicitly allows for full token display, understanding the security implications.
affects: 4.8.0 and later
gotchaHandling of non-ASCII metadata keys on Python 3 has historically had issues, particularly with receiving such metadata. While some fixes have been implemented for sending, receiving might still be problematic in certain older versions.fixEnsure you are on the latest stable version of `python-swiftclient`. If issues persist, consider encoding/decoding metadata keys to ASCII where possible, or consult the OpenStack Swift documentation for character set best practices.
affects: < 3.8.1 (sending fixed, receiving might still be an issue)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'swiftclient'
The `python-swiftclient` library is not installed in the current Python environment.
fixInstall the library using pip: `pip install python-swiftclient`
swiftclient.exceptions.ClientException: Unauthorized
The authentication credentials (e.g., username, password, project name, auth URL) provided are incorrect or invalid, preventing access to the Swift service.
fixVerify that `os_auth_url`, `os_username`, `os_password`, `os_tenant_name` (or `os_project_name`, `os_user_domain_name`, etc.) are correctly set and that the user has the necessary permissions. Example: `conn = Connection(auth_version='3', user='YOUR_USERNAME', key='YOUR_PASSWORD', os_options={'project_name': 'YOUR_PROJECT_NAME'}, authurl='YOUR_AUTH_URL/v3')` swiftclient.exceptions.ClientException: [Errno 111] Connection refused
The client failed to establish a network connection to the Swift service endpoint, often due to an incorrect URL, firewall blocking the connection, or the Swift server being down.
fixCheck the `os_auth_url` or storage URL for typos, verify network connectivity to the Swift endpoint from your client, and ensure the Swift service is running and accessible.
swiftclient.exceptions.ClientException: Container Not Found
The specified container name does not exist in the Swift account, or the authenticated user does not have permission to access it.
fixDouble-check the exact spelling of the container name. Ensure the container actually exists and that the authenticated user has the necessary access rights to it.
Upgrade
Version history
4.11.0latest on PyPI · released Aug 28, 2026
Audit
Dependencies
requestsrequiredCore HTTP client for making API calls.
keystoneauth1optionalCommonly used for authentication against Keystone identity service, often a de-facto dependency for modern OpenStack deployments.