{"id":3430,"library":"cloudinary","title":"Cloudinary Python SDK","description":"The Cloudinary Python SDK provides a comprehensive platform for managing digital media, including image and video upload, transformation, optimization, and delivery capabilities. It supports general Python applications as well as the Django framework. Currently at version 1.44.1, the library is actively maintained with frequent updates, typically focusing on new feature additions, API enhancements, and security improvements.","status":"active","version":"1.44.1","language":"en","source_language":"en","source_url":"https://github.com/cloudinary/pycloudinary","tags":["image management","video management","CDN","upload","transformation","Django","media processing"],"install":[{"cmd":"pip install cloudinary","lang":"bash","label":"Install core SDK"},{"cmd":"pip install python-dotenv","lang":"bash","label":"Optional: For local .env configuration"}],"dependencies":[{"reason":"Recommended for managing API credentials in local development environment files (.env).","package":"python-dotenv","optional":true}],"imports":[{"symbol":"cloudinary","correct":"import cloudinary"},{"symbol":"uploader","correct":"import cloudinary.uploader"},{"symbol":"api","correct":"import cloudinary.api"},{"note":"Used for simplified image URL generation.","symbol":"CloudinaryImage","correct":"from cloudinary import CloudinaryImage"},{"note":"Django-specific model field for storing Cloudinary asset URLs.","symbol":"CloudinaryField","correct":"from cloudinary.models import CloudinaryField"},{"note":"Django-specific form field for uploading files to Cloudinary.","symbol":"CloudinaryFileField","correct":"from cloudinary.forms import CloudinaryFileField"}],"quickstart":{"code":"import os\nfrom dotenv import load_dotenv\nimport cloudinary\nimport cloudinary.uploader\nimport cloudinary.api\n\n# Load environment variables from .env file (for local development)\nload_dotenv()\n\n# Configure Cloudinary using the CLOUDINARY_URL environment variable\n# Example: CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>\n# Ensure this variable is set in your environment or .env file.\ncloudinary.config(secure=True) # Forces HTTPS URLs\n\n# Check if configuration is successful (optional, for debugging)\nif not cloudinary.config().cloud_name:\n    print(\"Cloudinary configuration missing. Please set CLOUDINARY_URL.\")\n    exit(1)\n\nprint(\"Cloudinary configured. Cloud name:\", cloudinary.config().cloud_name)\n\n# --- Example: Upload an image ---\n# Replace 'my_local_image.jpg' with a path to a local image or a remote URL.\n# For a real application, handle file paths dynamically.\ntry:\n    upload_result = cloudinary.uploader.upload(\n        \"https://cloudinary-devs.github.io/cld-docs-assets/assets/images/butterfly.jpeg\",\n        public_id=\"quickstart_butterfly_example\",\n        unique_filename=False,\n        overwrite=True\n    )\n    print(\"\\nUpload successful:\")\n    print(\"Public ID:\", upload_result['public_id'])\n    print(\"Secure URL:\", upload_result['secure_url'])\n\n    # --- Example: Generate a transformed URL ---\n    transformed_url = cloudinary.utils.cloudinary_url(\n        upload_result['public_id'],\n        width=100,\n        height=150,\n        crop=\"fill\"\n    )[0]\n    print(\"Transformed URL (fill 100x150):\", transformed_url)\n\n    # --- Example: Get asset details (Admin API) ---\n    asset_details = cloudinary.api.resource(upload_result['public_id'])\n    print(\"\\nAsset details:\")\n    print(f\"Format: {asset_details['format']}, Bytes: {asset_details['bytes']}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to Python 3.8+ for full compatibility and security. (Recommended Python 3.8+)","message":"Python 2.x reached End of Life in January 2020. While older SDK versions might have supported Python 2.7, current and actively maintained versions of the Cloudinary Python SDK are developed for Python 3.x. Using Python 2.x may lead to compatibility issues and security vulnerabilities.","severity":"breaking","affected_versions":"<=1.x"},{"fix":"Always use environment variables (e.g., `CLOUDINARY_URL` or `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, `CLOUDINARY_API_SECRET`) and ensure your `.env` files are excluded from version control (via `.gitignore`). Load them using libraries like `python-dotenv`.","message":"Cloudinary API Key and Secret are sensitive credentials. Exposing them in source code or version control (e.g., directly in `settings.py` or `.env` files committed to Git) is a significant security risk.","severity":"gotcha","affected_versions":"All"},{"fix":"Structure your imports and configuration: `import cloudinary`, then `cloudinary.config(...)`, then `import cloudinary.uploader`, `import cloudinary.api`.","message":"When configuring Cloudinary globally (e.g., with `cloudinary.config()`) and using advanced settings like a proxy, the `cloudinary.config()` call must occur *before* importing `cloudinary.uploader` and `cloudinary.api` to ensure the settings are applied correctly for those modules.","severity":"gotcha","affected_versions":"All"},{"fix":"Define and utilize signed or unsigned upload presets via the Cloudinary Console or Admin API to manage upload options and transformations securely for client-side uploads. Use `upload_preset` parameter in your upload calls.","message":"Direct browser uploads (from client-side code) should primarily use 'unsigned upload presets'. Unsigned requests have a restricted set of parameters for security reasons. Other desired transformations or settings should be defined within the upload preset itself, rather than directly in the unsigned upload call.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}