Cloudinary Python SDK

Upload, transform, optimize, and manage images and videos with Cloudinary from Python or Django — the cloudinary package on PyPI.

Install

pip install cloudinary

Quick start

Set your API environment variable (Console > Settings > API Keys):

export CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>

Upload an image and get an optimized delivery URL:

import cloudinary
import cloudinary.uploader  # cloudinary.uploader must be imported explicitly

# Configuration is read from CLOUDINARY_URL automatically.


def main():
    # Upload a remote image (a local file path works the same way)
    result = cloudinary.uploader.upload(
        "https://res.cloudinary.com/demo/image/upload/sample.jpg",
        public_id="quickstart-sample",
    )
    print("Uploaded: {0}".format(result["public_id"]))

    # Build a 400x400 auto-cropped URL with automatic format and quality
    url = cloudinary.CloudinaryImage(result["public_id"]).build_url(
        width=400,
        height=400,
        crop="fill",
        gravity="auto",
        fetch_format="auto",
        quality="auto",
        secure=True,
    )
    print("Optimized URL: {0}".format(url))


if __name__ == "__main__":
    try:
        main()
    except Exception as error:
        print("Quick start failed: {0}".format(error))
        print("Check that CLOUDINARY_URL is set (Console > Settings > API Keys).")
        raise SystemExit(1)

Save as quickstart.py and run python quickstart.py. Create a free account if you don't have one — or call cloudinary.provisioning.create_cloud() to provision one without signing up.

Common tasks

• Get Cloudinary credentials
• Upload an image
• Upload a large video
• Sign a browser upload
• Transform and deliver an image
• Transform and deliver a video
• Search and manage assets
• Organize and share collections
• Moderate an upload
• Use structured metadata
• Use with Django
• Troubleshoot errors

Runnable versions live in examples/ — each is a complete file you can run directly.

When to use this SDK

Use this package in Python server-side code, including Django: uploads, signed operations, asset administration, search, moderation, and delivery URL generation.

For other jobs, better-fitting tools exist:

• Browser or frontend framework rendering: the frontend SDKs (md).
• Complete in-browser upload UI: Upload Widget (md).
• Text-to-image generation and image-to-video: platform APIs (md), not wrapped by this package.
• Multi-step media workflow automation: MediaFlows (md).
• Interactive agent-driven asset operations: Cloudinary MCP servers and Skills (md).

The full capability map — plus the Skills, MCP servers, and CLI worth setting up first — is in cloudinary/docs/platform-capabilities.md.

Status and compatibility

Stable, actively maintained. See CHANGELOG.md.

The table lists what CI tests on every commit. Older Python and Django releases are supported on a best-effort basis.

Documentation

• Bundled task docs — ship inside the package, version-matched.
• Python and Django SDK guide — the full documentation (md).
• Python quick start — a short end-to-end walkthrough (md).
• Transformation and REST API references — syntax and examples for all SDKs (md).

Documentation links in this README point at the browsable HTML page, with an (md) companion link that returns the same page as raw Markdown. Inside cloudinary/docs/ and examples/ the links are Markdown-only, since those files are written to be read by coding agents. Either form works for any page: add .md for Markdown, drop it for HTML.

For AI coding agents

• Contributing to this repo: read AGENTS.md.
• Using the installed package: the Markdown docs in the installed package's cloudinary/docs/ directory match your installed version and are the source of truth. Locate them with python -c "import cloudinary, pathlib; print(pathlib.Path(cloudinary.__file__).parent / 'docs')", and start with platform-capabilities before assuming a feature exists.

Support

• SDK bugs and feature requests: GitHub issues
• Account and platform questions: Cloudinary support
• Sample projects: samples/ and the Django Photo Album
• Contributing: CONTRIBUTING.md

More resources: Cloudinary Academy for courses, code explorers and feature demos, and the Cloudinary roadmap.

Security

See SECURITY.md for private vulnerability reporting. Keep your api_secret in server-side code; for client uploads, use the server-signed pattern in Sign a browser upload.

License

Released under the MIT license — see LICENSE. Copyright (c) Cloudinary Ltd.