Multiple file uploads in FastAPI - Step-by-Step Execution

Concept Flow - Multiple file uploads

Client sends POST request with multiple files

↓

FastAPI receives request

↓

Extract files list from request

↓

Process each file in the list

↓

Return response with file details

This flow shows how FastAPI handles multiple files sent in one request by extracting and processing each file before responding.

Execution Sample

FastAPI

from fastapi import FastAPI, File, UploadFile
from typing import List

app = FastAPI()

@app.post("/uploadfiles/")
async def upload_files(files: List[UploadFile] = File(...)):
    return {"filenames": [file.filename for file in files]}

This FastAPI endpoint accepts multiple uploaded files and returns their filenames.

Execution Table

Step	Action	Files List State	Processing File	Output
1	Receive POST request with 3 files	files = [file1, file2, file3]	None yet	None yet
2	Extract files list from request	files = [file1, file2, file3]	None yet	None yet
3	Process first file	files = [file1, file2, file3]	file1 (filename: 'a.txt')	Add 'a.txt' to output list
4	Process second file	files = [file1, file2, file3]	file2 (filename: 'b.jpg')	Add 'b.jpg' to output list
5	Process third file	files = [file1, file2, file3]	file3 (filename: 'c.pdf')	Add 'c.pdf' to output list
6	Return response	files = [file1, file2, file3]	None	{"filenames": ["a.txt", "b.jpg", "c.pdf"]}
7	End	No more files to process	None	Response sent to client

💡 All files processed and response returned with filenames list

Variable Tracker

Variable	Start	After 1	After 2	After 3	Final
files	None	[file1, file2, file3]	[file1, file2, file3]	[file1, file2, file3]	None (after response)
output list	[]	["a.txt"]	["a.txt", "b.jpg"]	["a.txt", "b.jpg", "c.pdf"]	["a.txt", "b.jpg", "c.pdf"]

Key Moments - 3 Insights

Why do we use List[UploadFile] instead of just UploadFile?

Because the endpoint expects multiple files, List[UploadFile] tells FastAPI to collect all uploaded files into a list, as shown in execution_table rows 1 and 2.

How does FastAPI know to extract multiple files from the request?

Using File(...) with a List type signals FastAPI to parse multiple files from the form data, demonstrated in execution_table step 2.

What happens if no files are sent in the request?

FastAPI will raise a validation error because File(...) requires at least one file, so the code won't reach processing steps (rows 3-6).

Visual Quiz - 3 Questions

Look at the execution_table at step 4, which file is being processed?

A file2 (b.jpg)

B file1 (a.txt)

C file3 (c.pdf)

D No file is processed at step 4

💡 Hint

Check the 'Processing File' column at step 4 in the execution_table

At which step does the response with filenames get returned?

A Step 5

B Step 6

C Step 3

D Step 7

💡 Hint

Look at the 'Output' column for the step where the JSON response is formed

If the client sends 5 files instead of 3, how does the 'output list' variable change?

A It will contain 3 filenames only

B It will be empty

C It will contain 5 filenames after processing

D It will cause an error

💡 Hint

Refer to variable_tracker row for 'output list' and how it grows with each processed file

Concept Snapshot

FastAPI multiple file uploads:
- Use List[UploadFile] with File(...) to accept many files
- FastAPI extracts all files into a list
- Process files by looping over the list
- Return response with file info
- Validation requires at least one file

Full Transcript

This example shows how FastAPI handles multiple file uploads. The client sends a POST request with several files. FastAPI receives the request and extracts all files into a list using List[UploadFile] with File(...). Then, it processes each file one by one, for example, collecting their filenames. Finally, it returns a JSON response listing all uploaded filenames. If no files are sent, FastAPI raises a validation error. This flow helps beginners understand how to accept and work with multiple files in FastAPI endpoints.

Practice

1. In FastAPI, which type hint should you use to accept multiple uploaded files in an endpoint?

easy

A. str with UploadFile

B. List[UploadFile] with File(...)

C. List[str] with File(...)

D. UploadFile without List

Solution

1. Step 1: Understand FastAPI file upload types

   FastAPI uses UploadFile to handle file uploads efficiently.

2. Step 2: Use List for multiple files

   To accept multiple files, you wrap UploadFile in a List and use File(...) to declare it as a file input.

3. Final Answer:

   List[UploadFile] with File(...) -> Option B

4. Quick Check:

   Multiple files = List[UploadFile] [OK]

Hint: Use List[UploadFile] with File(...) for multiple files [OK]

Common Mistakes:

• Using UploadFile without List for multiple files
• Using List[str] which expects strings, not files
• Confusing str type with file uploads

2. Which of the following is the correct syntax to declare a FastAPI endpoint that accepts multiple files named 'files'?

easy

A. files: List[UploadFile] = File(...)

B. files: UploadFile = File(...)

C. files: List[str] = File(...)

D. files: str = UploadFile(...)

Solution

1. Step 1: Check parameter type for multiple files

   Multiple files require List[UploadFile] type hint.

2. Step 2: Use File(...) to mark as file input

   File(...) is needed to tell FastAPI this is a file upload field.

3. Final Answer:

   files: List[UploadFile] = File(...) -> Option A

4. Quick Check:

   Multiple files syntax = List[UploadFile] = File(...) [OK]

Hint: Use List[UploadFile] = File(...) for multiple files param [OK]

Common Mistakes:

• Using UploadFile without List for multiple files
• Using List[str] which is incorrect for files
• Assigning UploadFile(...) instead of File(...)

3. Given this FastAPI endpoint code, what will be the output if two files named 'a.txt' and 'b.txt' are uploaded?

from fastapi import FastAPI, File, UploadFile
from typing import List

app = FastAPI()

@app.post('/upload')
async def upload(files: List[UploadFile] = File(...)):
    return {"filenames": [file.filename for file in files]}

medium

A. {"filenames": ["a.txt", "b.txt"]}

B. {"filenames": ["files", "files"]}

C. {"filenames": []}

D. Runtime error due to wrong type

Solution

1. Step 1: Understand the endpoint logic

   The endpoint returns a dictionary with a list of filenames extracted from the uploaded files.

2. Step 2: Check the uploaded files names

   Two files named 'a.txt' and 'b.txt' are uploaded, so their filenames will be returned in the list.

3. Final Answer:

   {"filenames": ["a.txt", "b.txt"]} -> Option A

4. Quick Check:

   Returned filenames list matches uploaded files [OK]

Hint: Returned filenames list matches uploaded files names [OK]

Common Mistakes:

• Expecting file content instead of filenames
• Confusing parameter name with file names
• Assuming empty list if files uploaded

4. What is wrong with this FastAPI endpoint for multiple file uploads?

from fastapi import FastAPI, File, UploadFile
from typing import List

app = FastAPI()

@app.post('/upload')
async def upload(files: UploadFile = File(...)):
    return {"count": len(files)}

medium

A. File(...) should be replaced with UploadFile(...)

B. Missing async keyword in function definition

C. len(files) is invalid because files is a string

D. files should be List[UploadFile] to accept multiple files

Solution

1. Step 1: Check parameter type for multiple files

   The parameter 'files' is typed as UploadFile, which accepts only one file.

2. Step 2: Correct type for multiple files

   To accept multiple files, it must be List[UploadFile].

3. Final Answer:

   files should be List[UploadFile] to accept multiple files -> Option D

4. Quick Check:

   Multiple files need List[UploadFile] type [OK]

Hint: Use List[UploadFile] for multiple files, not UploadFile alone [OK]

Common Mistakes:

• Using UploadFile instead of List[UploadFile] for multiple files
• Confusing File(...) with UploadFile(...)
• Forgetting async keyword (though present here)

5. You want to create a FastAPI endpoint that accepts multiple files and returns a JSON with each file's name and size in bytes. Which code snippet correctly implements this?

hard

A. async def upload(files: List[str] = File(...)):
return [{"name": f, "size": 0} for f in files]

B. async def upload(files: UploadFile = File(...)):
return [{"name": files.filename, "size": len(await files.read())}]

C. async def upload(files: List[UploadFile] = File(...)):
results = []
for file in files:
content = await file.read()
results.append({"name": file.filename, "size": len(content)})
return results

D. async def upload(files: List[UploadFile] = File(...)):
return [{"name": file.name, "size": file.size} for file in files]

Solution

1. Step 1: Accept multiple files with correct type

   Use List[UploadFile] with File(...) to accept multiple files.

2. Step 2: Read each file content to get size

   Use await file.read() to get bytes, then len() to get size.

3. Step 3: Return list of dicts with name and size

   Build a list of dictionaries with filename and size for each file.

4. Final Answer:

   Code snippet that correctly reads files and returns name and size -> Option C

5. Quick Check:

   Read files async, return name and size list [OK]

Hint: Read files async, use len(content) for size, return list [OK]

Common Mistakes:

• Using UploadFile without List for multiple files
• Trying to get size without reading file content
• Using wrong attribute names like file.name or file.size