Flask Wiki
Home Introduction

Static Files in Flask

Static files like CSS, JavaScript, and images are essential for creating a complete web application. Flask makes it easy to serve these files with its built-in static file handling.

Important
By default, Flask serves static files from a folder named static in your application's root directory.

Setting Up Your Static Files Directory

The standard structure for static files in a Flask application is: 

your_app/
├── static/
│   ├── css/
│   │   ├── main.css
│   │   └── styles.css
│   ├── js/
│   │   ├── script.js
│   │   └── app.js
│   └── img/
│       ├── logo.png
│       └── banner.jpg
├── templates/
│   └── ...
└── app.py

When you set up your Flask application, the static directory is automatically recognized, and Flask will serve files from this directory when accessed via the

/static/
URL path.

Using Static Files in Templates

To reference static files in your templates, use the

url_for()
function with the static endpoint:

Linking CSS Files

<!-- In your HTML template -->
<link rel="stylesheet" href="/static/css/main.css">

Including JavaScript Files

<!-- At the bottom of your HTML template -->
<script src="/static/js/script.js"></script>

Displaying Images

<img src="/static/img/logo.png" alt="Logo">

Using

url_for()
is recommended over hardcoding paths because:

  • It works regardless of where your application is mounted (root URL or subdirectory)
  • It automatically handles cache busting when needed
  • If you ever change your static file structure, you only need to update your Flask configuration

Customizing the Static Files Directory

You can customize the location of your static files by changing the Flask app configuration: 

from flask import Flask

app = Flask(__name__, 
    static_folder='path/to/static',  # Change static files directory
    static_url_path='/assets'        # Change URL prefix (default is /static)
)

# Now files will be served from /assets/* instead of /static/*

After this change, you would reference files like this: 

<link rel="stylesheet" href="/static/css/main.css">

Note that while the URL path changes, the way you reference files with

url_for()
remains the same, which is one of its benefits.

Efficient Static File Serving

For development, Flask's built-in static file serving is fine. However, for production, you should use a dedicated web server or CDN to serve static files for better performance.

Some Options for Production:

  • Configure Nginx or Apache to serve your static files directly
  • Use a CDN like Cloudflare, AWS CloudFront, or Google Cloud CDN
  • Use Flask-Assets or similar extensions to minify and bundle your static files
Production Warning
Never use Flask's built-in server or static file handling in production environments.

Best Practices

  1. Organize your static files by type (css, js, img, etc.)
  2. Use versioning or fingerprinting for cache busting
  3. Minify CSS and JavaScript for production
  4. Optimize images to reduce file size
  5. Consider using a CSS preprocessor like SASS or LESS for large projects
  6. Use a JavaScript build system like Webpack for complex front-end code
  7. Always use
    url_for('static', filename='...')
    rather than hardcoded paths
Next: Learn about using JavaScript in Flask →