File upload (single file) in FastAPI - Step-by-Step Execution

Concept Flow - File upload (single file)

Client sends HTTP POST request with file

↓

FastAPI receives request

↓

Extract file from request using UploadFile

↓

Read file content or save file

↓

Return response to client

The client sends a file in a POST request. FastAPI extracts the file, processes it, then sends a response.

Execution Sample

FastAPI

from fastapi import FastAPI, File, UploadFile
app = FastAPI()

@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
    content = await file.read()
    return {"filename": file.filename, "size": len(content)}

This code defines a FastAPI endpoint to receive one uploaded file and returns its name and size.

Execution Table

Step	Action	Input/State	Output/State
1	Client sends POST request	File attached in form-data	Request received by FastAPI
2	FastAPI extracts file	Request with file	UploadFile object created with filename and file stream
3	Read file content	UploadFile object	File bytes read into 'content' variable
4	Return response	Filename and content size	JSON response with filename and size sent to client
5	Client receives response	JSON with filename and size	Upload complete confirmation

💡 File read and response sent, request handling complete

Variable Tracker

Variable	Start	After Step 3	Final
file	UploadFile object not created	UploadFile object with filename and stream	Same UploadFile object
content	Undefined	File bytes read from UploadFile	Same bytes content

Key Moments - 3 Insights

Why do we use UploadFile instead of bytes directly?

UploadFile provides a file-like interface and metadata like filename. See step 2 in execution_table where FastAPI creates UploadFile object from request.

What does await file.read() do?

It reads the entire file content asynchronously into memory, shown in step 3 of execution_table where content variable gets file bytes.

Why do we return filename and size?

To confirm the file was received and processed. Step 4 shows returning this info as JSON response.

Visual Quiz - 3 Questions

Look at the execution_table, what is the state of 'file' after step 2?

A An UploadFile object with filename and stream

B A bytes object containing file data

C A string with the filename only

D Undefined, file is not created yet

💡 Hint

Check the 'Output/State' column in step 2 of execution_table

At which step does the server read the actual file content?

A Step 1

B Step 2

C Step 3

D Step 4

💡 Hint

Look for 'Read file content' action in execution_table

If the client sends no file, what will happen in this flow?

A The endpoint returns filename as empty string

B FastAPI raises a validation error before step 2

C FastAPI creates an empty UploadFile object

D The file variable is None and code runs normally

💡 Hint

Recall that File(...) makes the file required, so missing file causes validation error

Concept Snapshot

FastAPI file upload endpoint:
- Use UploadFile with File(...) to receive single file
- Await file.read() to get bytes content
- Access file.filename for original name
- Return info or save file as needed
- File is sent in POST request form-data

Full Transcript

This example shows how FastAPI handles a single file upload. The client sends a POST request with a file attached. FastAPI receives the request and creates an UploadFile object representing the uploaded file. We then read the file content asynchronously using await file.read(). Finally, the server returns a JSON response with the filename and size of the uploaded file. This confirms the file was received and processed. If no file is sent, FastAPI will raise a validation error because the file parameter is required. This flow helps beginners see each step from request to response clearly.

Practice

1. In FastAPI, which parameter type is used to accept a single uploaded file in an endpoint?

easy

A. List[UploadFile]

B. str

C. UploadFile

D. int

Solution

1. Step 1: Understand FastAPI file upload types

   FastAPI uses UploadFile to handle file uploads efficiently.

2. Step 2: Identify single file upload parameter

   For a single file, the parameter type is UploadFile, not a list or primitive type.

3. Final Answer:

   <code>UploadFile</code> -> Option C

4. Quick Check:

   Single file upload uses UploadFile [OK]

Hint: Use UploadFile for single file upload in FastAPI [OK]

Common Mistakes:

• Using str or int instead of UploadFile
• Using List[UploadFile] for single file
• Not importing UploadFile from fastapi

2. Which of the following is the correct way to declare a FastAPI endpoint parameter to accept a single file upload?

easy

A. file: str = File(...)

B. file: bytes = File(...)

C. file: UploadFile

D. file: UploadFile = File(...)

Solution

1. Step 1: Check parameter declaration for file upload

   FastAPI requires File(...) to mark the parameter as a file upload.

2. Step 2: Match type with File marker

   The type must be UploadFile combined with File(...) for single file upload.

3. Final Answer:

   file: UploadFile = File(...) -> Option D

4. Quick Check:

   UploadFile with File(...) is correct syntax [OK]

Hint: Use UploadFile = File(...) to accept single file [OK]

Common Mistakes:

• Omitting File(...) marker
• Using str or bytes instead of UploadFile
• Not assigning default File(...)

3. What will be the output of this FastAPI endpoint when a file named 'test.txt' with content 'hello' is uploaded?

from fastapi import FastAPI, UploadFile, File
app = FastAPI()

@app.post('/upload')
async def upload(file: UploadFile = File(...)):
    content = await file.read()
    return {'filename': file.filename, 'content_type': file.content_type, 'size': len(content)}

medium

A. {'filename': 'test.txt', 'content_type': 'text/plain', 'size': 5}

B. {'filename': 'test.txt', 'content_type': 'application/octet-stream', 'size': 0}

C. {'filename': '', 'content_type': '', 'size': 5}

D. RuntimeError due to missing await

Solution

1. Step 1: Read file content asynchronously

   The code uses await file.read() to get the file bytes, so content length is 5 for 'hello'.

2. Step 2: Return file info correctly

   Filename is 'test.txt', content type is 'text/plain' (default for .txt), size is length of content (5).

3. Final Answer:

   {'filename': 'test.txt', 'content_type': 'text/plain', 'size': 5} -> Option A

4. Quick Check:

   File info returned matches uploaded file [OK]

Hint: Await file.read() to get content size correctly [OK]

Common Mistakes:

• Not awaiting file.read() causing empty content
• Assuming wrong content_type
• Returning filename as empty string

4. Identify the error in this FastAPI endpoint code for single file upload:

from fastapi import FastAPI, UploadFile
app = FastAPI()

@app.post('/upload')
def upload(file: UploadFile = File(...)):
    content = file.read()
    return {'filename': file.filename, 'size': len(content)}

medium

A. Missing import of File from fastapi

B. All of the above

C. file.read() should be awaited in async function

D. Endpoint function must be async to await file.read()

Solution

1. Step 1: Check imports and function signature

   The code misses importing File and the function is not async but calls file.read() which is async.

2. Step 2: Identify async usage and await

   To read file content, function must be async and use await file.read().

3. Final Answer:

   All of the above -> Option B

4. Quick Check:

   Missing import, async, and await cause errors [OK]

Hint: Import File, make function async, await file.read() [OK]

Common Mistakes:

• Forgetting to import File
• Using sync function with async file.read()
• Not awaiting file.read()

5. You want to create a FastAPI endpoint that accepts a single file upload and returns the file's name, content type, and first 10 bytes as a UTF-8 string. Which code snippet correctly implements this?

hard

A. from fastapi import FastAPI, UploadFile, File
app = FastAPI()

@app.post('/upload')
async def upload(file: UploadFile = File(...)):
content = await file.read()
preview = content[:10].decode('utf-8')
return {'filename': file.filename, 'content_type': file.content_type, 'preview': preview}

B. from fastapi import FastAPI, UploadFile
app = FastAPI()

@app.post('/upload')
def upload(file: UploadFile):
content = file.read()
preview = content[:10].decode('utf-8')
return {'filename': file.filename, 'content_type': file.content_type, 'preview': preview}

C. from fastapi import FastAPI, UploadFile, File
app = FastAPI()

@app.post('/upload')
async def upload(file: bytes = File(...)):
preview = file[:10].decode('utf-8')
return {'filename': 'unknown', 'content_type': 'unknown', 'preview': preview}

D. from fastapi import FastAPI, UploadFile, File
app = FastAPI()

@app.post('/upload')
async def upload(file: UploadFile = File(...)):
content = await file.read()
preview = content.decode('utf-8')[:10]
return {'filename': file.filename, 'content_type': file.content_type, 'preview': preview}

Solution

1. Step 1: Use async function with UploadFile and File(...)

   Correct signature is async def with parameter file: UploadFile = File(...).

2. Step 2: Read file content and decode first 10 bytes

   Read content with await file.read(), then slice first 10 bytes and decode to UTF-8 string.

3. Step 3: Return filename, content_type, and preview string

   Return dictionary with correct file info and preview snippet.

4. Final Answer:

   Option A code snippet -> Option A

5. Quick Check:

   Async read, slice, decode first 10 bytes [OK]

Hint: Await read, slice first 10 bytes, decode UTF-8 [OK]

Common Mistakes:

• Using sync function without await
• Decoding entire content before slicing
• Using bytes type instead of UploadFile