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
- 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.
| 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 withpython -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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file cloudinary-1.46.1.tar.gz.
File metadata
- Download URL: cloudinary-1.46.1.tar.gz
- Upload date:
- Size: 231.2 kB
- Tags: Source
- Uploaded using 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
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0f94976106aa7e10edf2f20169329a7801ef9a7b93006c867b5694454cf10097
|
|
| MD5 |
1da0963c14aefa03c0065b2db911bc18
|
|
| BLAKE2b-256 |
0dc4cefd6ab483737c8a73295f6d51c692bb32339ae7feab79d85fb9d50d51c6
|
File details
Details for the file cloudinary-1.46.1-py3-none-any.whl.
File metadata
- Download URL: cloudinary-1.46.1-py3-none-any.whl
- Upload date:
- Size: 192.1 kB
- Tags: Python 3
- Uploaded using 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
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b8ed6a2b1c467b7d57a703504379a2f0d9e0a28d33f4654859eb7124e21dff53
|
|
| MD5 |
38712e32822b85d636bc3ee8f6f19e20
|
|
| BLAKE2b-256 |
ff81bc3a00d0530429c9a4bc760c76ef95936a98e38d53bb1f6b5b8978df153a
|
