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

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.

SDK version	Python	Django
1.x	3.10 – 3.14	4.2, 5.0, 5.1, 5.2, 6.0

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.

Metadata

Release files for cloudinary 1.46.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cloudinary 1.46.1
File	Size	Uploaded
cloudinary-1.46.1.tar.gz	231.2 kB	Aug 27, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cloudinary 1.46.1
File	Interpreter	ABI	Platform	Reset
cloudinary-1.46.1-py3-none-any.whl 192.1 kB Aug 27, 2026	Python 3	none	any	Details

Total release size: 423.3 kB

Release files / cloudinary-1.46.1.tar.gz

Download URL	cloudinary-1.46.1.tar.gz
Size	231.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`0f94976106aa7e10edf2f20169329a7801ef9a7b93006c867b5694454cf10097`
BLAKE2b-256 checksum How to use checksums	`0dc4cefd6ab483737c8a73295f6d51c692bb32339ae7feab79d85fb9d50d51c6`
Upload date	Aug 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.7.1 importlib_metadata/4.8.3 pkginfo/1.8.2 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.6.9`

Release files / cloudinary-1.46.1-py3-none-any.whl

Download URL	cloudinary-1.46.1-py3-none-any.whl
Size	192.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b8ed6a2b1c467b7d57a703504379a2f0d9e0a28d33f4654859eb7124e21dff53`
BLAKE2b-256 checksum How to use checksums	`ff81bc3a00d0530429c9a4bc760c76ef95936a98e38d53bb1f6b5b8978df153a`
Upload date	Aug 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.7.1 importlib_metadata/4.8.3 pkginfo/1.8.2 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.6.9`