Upload methods with Python

This tutorial covers two ways to upload content to Box by using the Python SDK: and . For chunked upload, you can use the SDK convenience method or manage the upload session yourself. Learn how each method works and how to combine with conflict handling to upload new files or update existing ones.

Method	Best for	Minimum size	Maximum size
	Small files, simple workflows	No minimum	50 MB
	Large files	20 MB	No limit

The code samples in this tutorial use the .

Prerequisites

A Box application with the scope (root_readwrite) enabled
Python 3.8 or later installed on your computer
The Box Python SDK v10.16.0 or later installed (pip install "boxsdk>=10.16")
An authenticated

Direct upload

To upload a file, call the upload_file method. For more information about the direct upload API, see . Run a first. If a file with the same name already exists, the error response includes the conflicting file ID. If you don’t want to override the content of the file with that name, change the name and upload it as a new file. The sample below assumes you want to override the file content, so it uses that ID to upload a :

Python v10

import os

from box_sdk_gen import (
    BoxAPIError,
    PreflightFileUploadCheckParent,
    UploadFileAttributes,
    UploadFileAttributesParentField,
    UploadFileVersionAttributes,
)


def upload_file_or_file_version(client, file_path, folder_id):
    file_size = os.path.getsize(file_path)
    file_name = os.path.basename(file_path)

    with open(file_path, "rb") as file_stream:
        try:
            client.uploads.preflight_file_upload_check(
                name=file_name,
                size=file_size,
                parent=PreflightFileUploadCheckParent(id=folder_id),
            )
            files = client.uploads.upload_file(
                UploadFileAttributes(
                    name=file_name,
                    parent=UploadFileAttributesParentField(id=folder_id),
                ),
                file_stream,
            )
            return files.entries[0]
        except BoxAPIError as err:
            if err.response_info.code != "item_name_in_use":
                raise
            file_id = err.response_info.context_info["conflicts"]["id"]
            file_stream.seek(0)
            files = client.uploads.upload_file_version(
                file_id,
                UploadFileVersionAttributes(name=file_name),
                file_stream,
            )
            return files.entries[0]

Calling upload_file on a folder creates a new file. Calling upload_file_version on an existing file uploads a new version.

Chunked upload

Use for files that are 20 MB or larger. Every chunked upload works through an : you create a session, , and to finalize the file. You have two options:

Convenience method: upload_big_file or upload_big_file_version runs all three steps for you.
Manual upload session: create the session, upload each part, and commit it yourself when you need full control.

Convenience method

The SDK uploads the file in parts for you:

upload_big_file uploads a new file to a folder.
upload_big_file_version uploads a new version of an existing file. Before it uploads each part, it checks whether Box already stores that part from the previous version and skips it if so, so the upload is faster. For details, see .

Run a preflight check first to handle name conflicts before you start the upload. When a file with the same name already exists, upload_chunked_file uses the conflicting file ID to upload a new version with upload_big_file_version:

Python v10

import os

from box_sdk_gen import BoxAPIError, PreflightFileUploadCheckParent


def upload_chunked_file(client, file_path, folder_id):
    file_size = os.path.getsize(file_path)
    file_name = os.path.basename(file_path)

    try:
        client.uploads.preflight_file_upload_check(
            name=file_name,
            size=file_size,
            parent=PreflightFileUploadCheckParent(id=folder_id),
        )
    except BoxAPIError as err:
        if err.response_info.code != "item_name_in_use":
            raise

        file_id = err.response_info.context_info["conflicts"]["id"]
        with open(file_path, "rb") as file_stream:
            return client.chunked_uploads.upload_big_file_version(
                file_id, file_stream, file_size
            )

    with open(file_path, "rb") as file_stream:
        return client.chunked_uploads.upload_big_file(
            file_stream, file_name, file_size, folder_id
        )

upload_big_file returns the new file. upload_big_file_version returns the updated file, or None when the returns 202 Accepted instead of a file.

Manual upload session

For full control over the upload, manage the session yourself. The upload_file_via_session helper uploads every part and commits the session for a session you pass in:

Python v10

import base64
import hashlib
from io import BytesIO

from box_sdk_gen import UploadPart


def upload_file_via_session(client, file_path, file_size, upload_session):
    file_sha1 = hashlib.sha1()
    parts: list[UploadPart] = []

    upload_part_url = upload_session.session_endpoints.upload_part
    commit_url = upload_session.session_endpoints.commit

    with open(file_path, "rb") as file_stream:
        part_size = upload_session.part_size
        for part_num in range(upload_session.total_parts):
            offset = part_num * part_size
            remaining = file_size - offset
            chunk_size = min(part_size, remaining)
            chunk = file_stream.read(chunk_size)

            part_sha1 = hashlib.sha1(chunk).digest()
            digest = f"sha={base64.b64encode(part_sha1).decode()}"
            content_range = (
                f"bytes {offset}-{offset + len(chunk) - 1}/{file_size}"
            )

            uploaded_part = client.chunked_uploads.upload_file_part_by_url(
                upload_part_url,
                BytesIO(chunk),
                digest,
                content_range,
            )
            parts.append(uploaded_part.part)
            file_sha1.update(chunk)

    content_sha1 = file_sha1.digest()
    digest = f"sha={base64.b64encode(content_sha1).decode()}"
    files = client.chunked_uploads.create_file_upload_session_commit_by_url(
        commit_url, parts, digest
    )
    return files.entries[0]

This helper uploads every part, even when most of a new version matches the previous version. To skip unchanged parts, use upload_big_file_version, or with create_file_upload_session_plan_by_url and only upload the parts listed in misses.

Create the session before calling the helper. Run a preflight check first, then use create_file_upload_session for a new file. When a file with the same name already exists, upload_file_manual falls back to create_file_upload_session_for_existing_file to upload a new version:

Python v10

import os

from box_sdk_gen import BoxAPIError, PreflightFileUploadCheckParent


def upload_file_manual(client, file_path, folder_id):
    file_size = os.path.getsize(file_path)
    file_name = os.path.basename(file_path)
    parent = PreflightFileUploadCheckParent(id=folder_id)

    try:
        client.uploads.preflight_file_upload_check(
            name=file_name,
            size=file_size,
            parent=parent,
        )
        upload_session = client.chunked_uploads.create_file_upload_session(
            folder_id, file_size, file_name
        )
    except BoxAPIError as err:
        if err.response_info.code != "item_name_in_use":
            raise

        file_id = err.response_info.context_info["conflicts"]["id"]
        upload_session = (
            client.chunked_uploads.create_file_upload_session_for_existing_file(
                file_id, file_size, file_name
            )
        )

    return upload_file_via_session(
        client, file_path, file_size, upload_session
    )

Getting started

Applications & integrations

Identity & access

Using the API

Troubleshooting

Content

Collaboration

Metadata & search

Events & webhooks

Users

Intelligent workflow

E-signatures

Security & compliance

Upload methods with Python

Prerequisites

Direct upload

Chunked upload

Convenience method

Manual upload session

Resources