Install & Compatibility
Where this runs
tested against v1.46.2 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.280s · 65.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.7s · import 0.256s · 21MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cloudinary
✓ import cloudinary
uploader
✓ import cloudinary.uploader
api
✓ import cloudinary.api
CloudinaryImage
✓ from cloudinary import CloudinaryImage
Used for simplified image URL generation.
CloudinaryField
✓ from cloudinary.models import CloudinaryField
Django-specific model field for storing Cloudinary asset URLs.
CloudinaryFileField
✓ from cloudinary.forms import CloudinaryFileField
Django-specific form field for uploading files to Cloudinary.
This quickstart demonstrates how to configure the Cloudinary Python SDK, upload an image from a remote URL, generate a transformed URL, and retrieve asset details using the Admin API. It emphasizes using environment variables (especially `CLOUDINARY_URL`) for secure configuration. For local development, `python-dotenv` is used to load these variables from a `.env` file.
import os
from dotenv import load_dotenv
import cloudinary
import cloudinary.uploader
import cloudinary.api
# Load environment variables from .env file (for local development)
load_dotenv()
# Configure Cloudinary using the CLOUDINARY_URL environment variable
# Example: CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>
# Ensure this variable is set in your environment or .env file.
cloudinary.config(secure=True) # Forces HTTPS URLs
# Check if configuration is successful (optional, for debugging)
if not cloudinary.config().cloud_name:
print("Cloudinary configuration missing. Please set CLOUDINARY_URL.")
exit(1)
print("Cloudinary configured. Cloud name:", cloudinary.config().cloud_name)
# --- Example: Upload an image ---
# Replace 'my_local_image.jpg' with a path to a local image or a remote URL.
# For a real application, handle file paths dynamically.
try:
upload_result = cloudinary.uploader.upload(
"https://cloudinary-devs.github.io/cld-docs-assets/assets/images/butterfly.jpeg",
public_id="quickstart_butterfly_example",
unique_filename=False,
overwrite=True
)
print("\nUpload successful:")
print("Public ID:", upload_result['public_id'])
print("Secure URL:", upload_result['secure_url'])
# --- Example: Generate a transformed URL ---
transformed_url = cloudinary.utils.cloudinary_url(
upload_result['public_id'],
width=100,
height=150,
crop="fill"
)[0]
print("Transformed URL (fill 100x150):", transformed_url)
# --- Example: Get asset details (Admin API) ---
asset_details = cloudinary.api.resource(upload_result['public_id'])
print("\nAsset details:")
print(f"Format: {asset_details['format']}, Bytes: {asset_details['bytes']}")
except Exception as e:
print(f"An error occurred: {e}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cloudinary'
The 'cloudinary' package is not installed in your Python environment or is not accessible within your project's virtual environment.
fixInstall the Cloudinary Python SDK using pip: `pip install cloudinary`
Missing required parameter - file
When attempting to upload an asset, the `file` parameter, which specifies the asset to upload (e.g., file path, URL, or file-like object), was either not provided or was empty/invalid.
fixEnsure that a valid and accessible file path, file-like object, Data URI, or remote URL is passed as the first argument to `cloudinary.uploader.upload()`.
Must supply cloud_name in tag or in configuration
The Cloudinary SDK requires your cloud_name (and often api_key and api_secret) to be configured globally or passed explicitly in API calls, but these credentials were not found or were incorrectly set.
fixConfigure your Cloudinary credentials globally using `cloudinary.config(cloud_name='your_cloud_name', api_key='your_api_key', api_secret='your_api_secret')` or ensure they are set as environment variables (e.g., `CLOUDINARY_URL`).
Failed to establish a new connection: [Errno 111] Connection refused
This network error typically occurs in deployment environments (like PythonAnywhere) when the application cannot connect to Cloudinary's API servers, often due to firewall restrictions, proxy requirements, or incorrect DNS resolution.
fixIf behind a proxy, configure the `api_proxy` setting in your Cloudinary configuration: `cloudinary.config(api_proxy='http://your_proxy_server:port')`. Otherwise, check network access rules for outbound connections.
Upgrade
Version history
1.46.2latest on PyPI · released Aug 27, 2026
Audit
Dependencies
python-dotenvoptionalRecommended for managing API credentials in local development environment files (.env).