Bottle — Single-File Micro Web Framework for Python

Introduction

Bottle is a Python micro web framework contained entirely in a single file with zero external dependencies. It is one of the oldest Python micro frameworks, predating Flask, and remains a practical choice when you need a small HTTP server with routing, templates, and static file serving without pulling in a dependency tree.

What Bottle Does

• Provides URL routing with dynamic parameters and filters in a single module
• Includes a built-in template engine with Python expression support
• Serves static files from a configurable directory
• Supports multiple WSGI server backends (gunicorn, paste, cherrypy, etc.)
• Handles file uploads, cookies, headers, and form data through a clean request API

Architecture Overview

Bottle consists of a single Python file (approximately 4,000 lines) that implements a WSGI application. Routes are stored in a routing table that compiles URL patterns into regular expressions at startup. When a request arrives, the router matches the path, extracts parameters, and calls the decorated handler function. The response is serialized according to the return type — strings become text, dicts become JSON, and generators are streamed.

Self-Hosting & Configuration

• Install with pip install bottle or copy bottle.py directly into your project
• Run with the built-in development server via run(host, port)
• Deploy behind gunicorn: gunicorn -w 4 myapp:app where app is the Bottle instance
• Configure template paths with bottle.TEMPLATE_PATH.insert(0, '/path/to/templates')
• Enable debug mode with run(debug=True) for auto-reload during development

Key Features

• Zero dependencies — the entire framework is one importable file
• Decorator-based routing that reads naturally in small applications
• Built-in SimpleTemplate engine with inline Python code
• Plugin system for adding database connections, authentication, and more
• Compatible with any WSGI server for production deployment

Comparison with Similar Tools

• Flask — similar micro approach but with Jinja2 and Werkzeug as dependencies, larger ecosystem
• FastAPI — async with automatic OpenAPI docs, better for typed APIs, heavier dependency tree
• Starlette — ASGI-based async framework, more suited for WebSocket and streaming workloads
• CherryPy — object-oriented HTTP framework, built-in multi-threaded server, more configuration

FAQ

Q: When should I use Bottle instead of Flask? A: When you want zero dependencies or need to embed a tiny HTTP server inside another application. For larger projects, Flask's ecosystem is broader.

Q: Can Bottle handle production traffic? A: Yes, when deployed behind a production WSGI server like gunicorn or uWSGI. The built-in server is for development only.

Q: Does Bottle support async/await? A: No. Bottle is a synchronous WSGI framework. For async support, consider Starlette or FastAPI.

Q: Is Bottle still maintained? A: Yes. Development continues at a stable pace with periodic releases for bug fixes and compatibility updates.

Sources

• https://github.com/bottlepy/bottle
• https://bottlepy.org