> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

# Python API Client

> Uploadcare Python & Django integrations handle uploads and further operations with files by wrapping Upload and REST APIs.

Uploadcare Python & Django integrations handle uploads and further operations
with files by wrapping Upload and REST APIs.

[GitHub →](https://github.com/uploadcare/pyuploadcare#readme)

## Features

Uploading ([Upload API](https://uploadcare.com/docs/api/upload/)):

* Upload files from a local storage and URLs (up to 5 TB)
* Multipart uploading for large files
* Uploading network to speed up uploading jobs (like CDN)

File management ([REST API](https://uploadcare.com/docs/api/rest/)):

* Get file info
* Perform various file operations (store/delete/copy/group)
* Detect unsafe and malicious content
* Encode and transform videos
* Convert documents and other files
* Recognize objects in the image
* Add arbitrary file metadata
* Manage webhooks

Image processing ([URL API](https://uploadcare.com/docs/api/url/)):

* Compression
* Geometry
* Colors
* Definition
* Image and text overlays
* Rotations
* Recognition
* File info
* Proxy (fetch)

Security features:

* Secure authentication
* Secure uploads (signed uploads)
* Secure delivery (signed URLs)
* Secure webhooks (signing secret)

## Installation

In order to install `pyuploadcare`, run these command in CLI:

```bash
pip install pyuploadcare
```

To use in Django project install with extra dependencies:

```bash
pip install pyuploadcare[django]
```

## Configuration

Add your Uploadcare API keys to Django settings:

```python
# settings.py
UPLOADCARE = {
    "pub_key": "YOUR_PUBLIC_KEY",
    "secret": "YOUR_SECRET_KEY",
}
```

For secure uploads, enable signed uploads:

```python
UPLOADCARE = {
    "pub_key": "YOUR_PUBLIC_KEY",
    "secret": "YOUR_SECRET_KEY",
    "signed_uploads": True,
}
```

For subdomain CDN addressing (recommended for high-traffic projects):

```python
UPLOADCARE = {
    "pub_key": "YOUR_PUBLIC_KEY",
    "secret": "YOUR_SECRET_KEY",
    "subdomains": True,
}
```

> **Note**
>
> **Note:** `subdomains` defaults to `False` in v6.2.x but will become the default in the next major release.

## REST API

Search files and manage tags directly through the REST API.

Searching files:

```python
result = uploadcare.search_files({"query": "invoice"})

for file in result.results:
    print(file.uuid, file.original_filename)
```

Managing file tags:

```python
file = uploadcare.file("YOUR_FILE_UUID")

file.update_tags(add=["featured"], delete=["draft"])

tags = file.get_tags()
```

See the [file search](https://uploadcare.com/docs/file-search/) and [file tags](https://uploadcare.com/docs/file-tags/) guides for the full parameter reference.

## Usage example

Here is an example how to include Uploadcare `ImageField` into an existing
Django project.

```python
from django import forms
from django.db import models

from pyuploadcare.dj.models import ImageField
from pyuploadcare.dj.forms import FileWidget, ImageField as ImageFormField

class Candidate(models.Model):
    photo = ImageField(blank=True, manual_crop='4:3')

# optional. provide advanced widget options:
# https://uploadcare.com/docs/file-uploader/configuration/
# https://uploadcare.com/docs/file-uploader/options/
class CandidateForm(forms.Form):
    photo = ImageField(widget=FileWidget(attrs={
        'source-list': 'local,url,camera',
        'camera-mirror': True,
    }))
```

## Widget

By default, pyuploadcare uses the File Uploader v1 widget (`FileWidget`). Pass any [File Uploader configuration attributes](https://uploadcare.com/docs/file-uploader/configuration/) via `attrs`:

```python
from pyuploadcare.dj.forms import FileWidget, ImageField as ImageFormField

class CandidateForm(forms.Form):
    photo = ImageFormField(widget=FileWidget(attrs={
        'source-list': 'local,url,camera',
        'camera-mirror': True,
    }))
```

To use the legacy jQuery-based widget instead:

```python
# settings.py
UPLOADCARE = {
    "pub_key": "YOUR_PUBLIC_KEY",
    "secret": "YOUR_SECRET_KEY",
    "use_legacy_widget": True,
    "legacy_widget": {
        "version": "3.x",
    },
}
```

> **Note**
>
> **Note:** In pyuploadcare v5.0, `FileWidget` was rewritten to use File Uploader v1. The jQuery-based widget is now `LegacyFileWidget`. If you are upgrading from v4.x, set `use_legacy_widget: True` to keep the old behavior, or migrate your widget configuration to File Uploader v1 attributes.

## Example Django project

Check out [example Django project](https://github.com/uploadcare/pyuploadcare-example).
It features:

* Project section
* Files section
* File Groups section
* Files uploading
* Documents conversion
* Video conversion
* Webhooks
* Posts section

## Requirements

* Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13

> **Note**
>
> **Note:** pyuploadcare requires Pydantic v2 (>=2.5.2). Projects on Pydantic v1 must upgrade before installing pyuploadcare v5.0+.

To use pyuploadcare with Python 3.6 or 3.7 please install `pyuploadcare < 5.0`.

To use pyuploadcare with Python 2.7 please install `pyuploadcare < 3.0`.

Django compatibility:

| Py/Dj | 2.2 | 3.0 | 3.1 | 3.2 | 4.0 | 4.1 | 4.2 | 5.0 | 5.1 | 5.2 |
| ----- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 3.8   | X   | X   | X   | X   | X   | X   | X   |     |     |     |
| 3.9   | X   | X   | X   | X   | X   | X   | X   |     |     |     |
| 3.10  |     |     |     | X   | X   | X   | X   | X   | X   | X   |
| 3.11  |     |     |     |     |     | X   | X   | X   | X   | X   |
| 3.12  |     |     |     |     |     |     | X   | X   | X   | X   |
| 3.13  |     |     |     |     |     |     |     |     | X   | X   |