When building web applications with Flask, file uploads are a common requirement, particularly for applications that handle images, videos, or documents. But uploading large files in Flask can be tricky. You might encounter timeouts, memory issues, or server-side crashes if you’re not careful.
In this article, we’ll dive deep into how to upload large files in Flask without timeout issues, the right way, without hitting timeout issues or overloading your server. Whether you’re building a media-heavy Flask app or an Odoo backend integration that needs to handle large CSVs, this guide is for you.
Table of Contents
Why does File Upload Timeout Issue Occur in Flask?
Before we get into the solution, let’s understand the problem.
Flask, by default, runs on the Werkzeug development server, which is great for debugging but not optimized for production. If a file is too large or the user’s upload speed is slow, the server may time out or run into memory limits.
Typical causes of timeout issues during uploads include:
- Default Flask request timeouts
- Web server (like Gunicorn or Nginx) timeouts
- Insufficient request body size allowed
- Lack of streaming or chunked upload handling
Best Practices for Uploading Large File in Flask Without Timeout Issue
Here’s how you can build a Flask app that can handle large file uploads smoothly:
Increase Maximum Request Size
Flask limits the maximum file size via the MAX_CONTENT_LENGTH configuration.
Set this in your app config:
from flask import Flask
app = Flask(__name__)
app.config['MAX_CONTENT_LENGTH'] = 2 * 1024 * 1024 * 1024 # 2 GB limitThis setting ensures that Flask accepts large files immediately. You can adjust this based on your application’s needs.
⚠️ If a file larger than this limit is uploaded, Flask will throw a
RequestEntityTooLargeexception.
So we have handled this RequestEntityTooLarge exception too, without crashing the application.
Handle RequestEntityTooLarge Exceptions
When someone uploads a file that exceeds the max content length, you should handle it with a custom error handler.
from flask import request, abort
from werkzeug.exceptions import RequestEntityTooLarge
@app.errorhandler(RequestEntityTooLarge)
def handle_file_too_large(e):
return "File is too large. Please upload a smaller file.", 413
This improves the user experience by displaying a friendly message instead of a crash.
We can also stream files instead of loading them into memory. It helps to avoid crashing the application while uploading the large files.
Stream Files Instead of Loading Into Memory
By default, Flask will load the whole request (including files) into memory. That’s inefficient and can crash your server with large files.
Instead, configure the request stream and handle uploads in chunks:
from flask import request
@app.route('/upload', methods=['POST'])
def upload():
file = request.files['file']
with open(f"/path/to/save/{file.filename}", 'wb') as f:
while chunk := file.stream.read(1024 * 1024): # Read in 1MB chunks
f.write(chunk)
return "File uploaded successfully!"This avoids memory overload and is ideal for 100 MB+ uploads.
Adjust Web Server Configs (Nginx, Gunicorn, etc.)
Flask alone isn’t the full picture—you also need to configure your production server properly.
If Using Gunicorn
Set a longer timeout and a larger worker class buffer.
gunicorn app:app --timeout 120 --worker-class geventIf Using Nginx
Set proper client_max_body_size and proxy_read_timeout.
server {
client_max_body_size 2048M;
proxy_read_timeout 120;
...
}This tells Nginx to allow uploads up to 2 GB and wait up to 2 minutes before timing out.
Use Asynchronous Uploads (Frontend + Backend)
If you’re uploading files from the frontend (React, Vue, HTML), consider using AJAX or the Fetch API with progress monitoring and chunked uploads.
This approach improves the user experience and gives you better control over error handling and retries.
Example using JavaScript:
const file = document.querySelector('#fileInput').files[0];
const formData = new FormData();
formData.append('file', file);
fetch('/upload', {
method: 'POST',
body: formData
})
.then(response => response.text())
.then(data => console.log(data));For huge files, you can split them into chunks client-side and upload one chunk at a time (Resumable.js or tus.io are great tools).
Secure Large File Upload in Flask
Don’t forget security! Large files pose risks like:
- Zip bombs
- Executable payloads
- Overwriting existing files
To protect your Flask app:
- Validate file extensions and MIME types
- Use a secure filename (
werkzeug.utils.secure_filename) - Store uploads in a separate directory (not in
/static) - Scan files using antivirus tools like ClamAV for sensitive apps
from werkzeug.utils import secure_filename
import os
UPLOAD_FOLDER = "/safe/uploads"
ALLOWED_EXTENSIONS = {'pdf', 'png', 'jpg', 'mp4'}
def allowed_file(filename):
return '.' in filename and filename.rsplit('.', 1)[1] in ALLOWED_EXTENSIONS
@app.route('/upload', methods=['POST'])
def upload_file():
file = request.files['file']
if file and allowed_file(file.filename):
filename = secure_filename(file.filename)
file.save(os.path.join(UPLOAD_FOLDER, filename))
return 'Upload successful'
return 'Invalid file type', 400
Monitor and Log Upload Activity
Add monitoring tools and proper logging so you can detect failed uploads, track server performance, and debug issues.
Use:
- Flask logging (
app.logger) - Prometheus + Grafana for performance
- Sentry or Rollbar for error tracking
Related Post:
>> Encoding and Decoding Using Base64 Strings in Python
>> Python HTTP Requests and Responses Using httpclient
>> 5 Free Hosting Platforms for Python Applications
Conclusion – Upload Large Files in Flask without timeout
Uploading large files in Flask can be challenging if you don’t plan, but with the right setup, it’s completely manageable. By increasing request limits, using streaming uploads, configuring your server properly, and handling files securely, you can avoid common timeout issues.
In short, if you’re wondering how to upload large files in Flask without timeout issues, the key is to combine Flask’s built-in features with smart backend practices. This ensures smooth performance, even for files in the hundreds of megabytes or more.
Thank You, Geeks!
