Programmable Media
Menu

Python quick start

Last updated: Mar-06-2025

This quick start lets you get an end-to-end implementation up and running using the Python SDK in 5 minutes or less.

On this page:

Rate this page:

1. Set up and configure the SDK

In a terminal in your Python3 environment, run the following code:

Python
pip3 install cloudinary
pip3 install python-dotenv

In your project, create a file called .env containing your API environment variable from your product environment credentials:

.env
Python
# Copy and paste your API environment variable
# =============================================

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

Important
  • When writing your own applications, follow your organization's policy on storing secrets and don't expose your API secret.
  • Don't store your .env under version control for maximum security.

In your project, create a new file called my_file.py. Copy and paste the following into this file:

my_file.py
Python

# Set your Cloudinary credentials
# ==============================
from dotenv import load_dotenv
load_dotenv()

# Import the Cloudinary libraries
# ==============================
import cloudinary
from cloudinary import CloudinaryImage
import cloudinary.uploader
import cloudinary.api

# Import to format the JSON responses
# ==============================
import json

# Set configuration parameter: return "https" URLs by setting secure=True  
# ==============================
config = cloudinary.config(secure=True)

# Log the configuration
# ==============================
print("****1. Set up and configure the SDK:****\nCredentials: ", config.cloud_name, config.api_key, "\n")

2. Upload an image

Copy and paste this into my_file.py:

my_file.py (continued)
Python
def uploadImage():

  # Upload the image and get its URL
  # ==============================

  # Upload the image.
  # Set the asset's public ID and allow overwriting the asset with new versions
  cloudinary.uploader.upload("https://cloudinary-devs.github.io/cld-docs-assets/assets/images/butterfly.jpeg", public_id="quickstart_butterfly", unique_filename = False, overwrite=True)

  # Build the URL for the image and save it in the variable 'srcURL'
  srcURL = CloudinaryImage("quickstart_butterfly").build_url()

  # Log the image URL to the console. 
  # Copy this URL in a browser tab to generate the image on the fly.
  print("****2. Upload an image****\nDelivery URL: ", srcURL, "\n")

3. Get and use details of the image

Copy and paste this into my_file.py:

my_file.py (continued)
Python
def getAssetInfo():

  # Get and use details of the image
  # ==============================

  # Get image details and save it in the variable 'image_info'.
  image_info=cloudinary.api.resource("quickstart_butterfly")
  print("****3. Get and use details of the image****\nUpload response:\n", json.dumps(image_info,indent=2), "\n")

  # Assign tags to the uploaded image based on its width. Save the response to the update in the variable 'update_resp'.
  if image_info["width"]>900:
    update_resp=cloudinary.api.update("quickstart_butterfly", tags = "large")
  elif image_info["width"]>500:
    update_resp=cloudinary.api.update("quickstart_butterfly", tags = "medium")
  else:
    update_resp=cloudinary.api.update("quickstart_butterfly", tags = "small")

  # Log the new tag to the console.
  print("New tag: ", update_resp["tags"], "\n")

4. Transform the image

Copy and paste this into my_file.py:

my_file.py (continued)
Python
def createTransformation():

  # Transform the image
  # ==============================

  transformedURL = CloudinaryImage("quickstart_butterfly").build_url(width = 100, height = 150, crop = "fill")

  # Log the URL to the console
  print("****4. Transform the image****\nTransfrmation URL: ", transformedURL, "\n")

  # Use this code instead if you want to create a complete HTML image element:
  # imageTag = cloudinary.CloudinaryImage("quickstart_butterfly").image(radius="max", effect="sepia")
  # print("****4. Transform the image****\nTransfrmation URL: ", imageTag, "\n")

5. Run your code

Copy and paste this into my_file.py:

my_file.py (continued)
Python
def main():
  uploadImage()
  getAssetInfo()
  createTransformation()
main();

In the terminal, run the following command: 

python3 my_file.py

The following original image is uploaded to Cloudinary, tagged appropriately and accessible via the URL shown below.

The transformed version of the image is accessible via the URL shown below.

Original image Original image
http://res.cloudinary.com/&ltcloud-name&gt/image/
upload/v1/quickstart_butterfly Transformed image Transformed image
http://res.cloudinary.com/&ltcloud-name&gt
/image/upload/e_sepia
r_max/v1/quickstart_butterfly

View the completed code

See the code above in action using this code playground.

Note
If you want to see the output:
  • Click Remix to Edit.
  • Copy your API environment variable value (i.e., only the portion after the equal sign, cloudinary://<api_key:api_secret@cloud_name).
  • Paste it into the Glitch .env file as the Variable Value for CLOUDINARY_URL.
  • Click Logs at the bottom of the screen.

This code is also available in GitHub

Next steps

  • Learn more about the Python SDK by visiting the other pages in this SDK guide.
  • Get comprehensive details about Cloudinary features and capabilities:

✔️ Feedback sent!