Bottle: a single-file Python WSGI micro-framework
bottle.py is a fast and simple micro-framework for python web-applications.
At a glance
- What is it?
- Bottle packs routing, a template engine, HTTP utilities and a development server into one dependency-free Python file. It suits small services and embedded apps, and it is a poor fit for projects that expect an ORM and an admin panel.
- Who is it for?
- Adopt Bottle for small WSGI services, internal tools and apps that must ship as one file with no dependencies beyond the standard library. Do not adopt it if you want an ORM, an admin interface or a large plugin ecosystem; Bottle provides none of these.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 21 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- bottlepy/bottle8,800 ★ · +10
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| bottlepy/bottle | 8.8k | 8.8k |
10 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem Bottle solves, and who it is for
Bottle targets the gap between a raw WSGI callable and a full framework. Writing a WSGI application by hand means handling the environ dictionary, status strings and header lists yourself. Bottle wraps that in decorators and request/response objects while staying small enough to read. The README describes it as "a fast, simple and lightweight WSGI micro web-framework for Python", distributed as a single file module with no dependencies other than the standard library. That single-file property is the real product. You can drop bottle.py into a project directory, or vendor it, without adding a dependency graph. The intended audience is someone building a small web application, an API endpoint, or an internal tool who does not want Django's project layout or Flask's dependency set. It is not aimed at teams that need an ORM, migrations, authentication backends or an admin UI; none of those appear anywhere in the README or the packaging metadata.
Routing, templates and the request object
The mechanism is decorator-based routing. A function is bound to a URL pattern, and dynamic segments are passed as arguments. The README's example uses @route('/hello/<name>') with a function taking name, so the pattern itself defines the parameter name and the call signature. Templates are handled by a built-in engine, with the README also listing support for mako, jinja2 and cheetah templates. The built-in engine is used inline in the example: template('<b>Hello {{name}}</b>!', name=name). Beyond routing and templates, the README lists utilities for form data, file uploads, cookies and headers, plus a built-in development server and adapters for WSGI-capable servers such as gunicorn, paste and cheroot. The architecture is therefore plain WSGI: Bottle is the application callable, and any WSGI server can host it. That is the whole data flow. A request arrives at the server, the server calls the Bottle app, Bottle matches the path to a route function, the return value becomes the response body, and the response object carries status and headers back out.
Installing Bottle and serving a first route
The README gives two install paths: install the latest stable release with pip install bottle, or download bottle.py into your project directory. The second option is marked unstable in the README, which is worth reading literally: the file at that URL tracks the main branch, not a release. For anything you intend to deploy, use the pip route.
pip install bottleAfter installation, the README's Hello World is the smallest complete application. Save it as a script and run it with Python.
from bottle import route, run, template
@route('/hello/<name>')
def index(name):
return template('<b>Hello {{name}}</b>!', name=name)
run(host='localhost', port=8080)The README states that you run this script or paste it into a Python console, then point your browser to http://localhost:8080/hello/world. You should see the rendered greeting with the name substituted. Two things are happening that matter later: run() starts the built-in development server, and the route pattern supplies the name argument. The development server is what the README calls it, a development server, and the same README points to gunicorn, paste and cheroot as the servers to use when that is not enough.
Where Bottle is the wrong choice
The absence of dependencies is also the absence of features. There is no ORM, no migration tool, no session store described in the README, and no authentication layer. If your application needs any of those, you are assembling them yourself or pulling in separate libraries, at which point the single-file advantage shrinks. The template story is similar: the built-in engine is described as fast, and the README lists support for mako, jinja2 and cheetah, but using any of them means adding dependencies back. Deployment is another boundary. Bottle is a WSGI framework, so it slots into WSGI servers, but the README does not document async support, and it does not document how to serve static files. If your application is mostly static assets with a thin dynamic layer, a WSGI micro-framework is not where the work is. Finally, the project's own classifier reads "Development Status :: 6 - Mature", which is a statement about stability, not about feature growth. Mature projects change slowly, and the release history bears that out: 0.13.2 in October 2024, 0.13.3 in April 2025, 0.13.4 in June 2025.
Bottle against Flask and FastAPI
The closest comparison in the Python micro-framework space is Flask. Both are WSGI frameworks with decorator routing, and both can be extended. The difference is what ships in the box. Flask depends on Werkzeug and Jinja2, which gives it a mature request/response layer and a template engine with a large ecosystem; Bottle ships its own versions of both inside one file with no dependencies. If you want the ecosystem, Flask is the better trade. If you want to vendor a framework into an application, Bottle is the one you can copy. FastAPI takes a different route entirely: it is built around type hints and async, with automatic OpenAPI schema generation. The Bottle README documents none of that, so the two are not competing on the same axis. The honest framing is that Bottle optimizes for footprint and portability, and every other framework on this list optimizes for something else.
Maintenance, licensing and upgrade cost
The repository is not archived, and the last push was on 2026-10-25, so the source tree sees current activity. Releases are infrequent: the three most recent came between October 2024 and June 2025, with 0.13.4 on 2025-06-15. The pyproject.toml requires Python 3.9 or newer, so old interpreters are out; check that before upgrading. The project is MIT licensed, and the README adds a carve-out worth noting: the Bottle logo is not covered by that licence and may be used as a link to the homepage or in direct context with the unmodified library, with other uses requiring you to ask first. That is a trademark-style restriction on an image, not on the code, so it does not affect redistribution of bottle.py. Upgrade cost is low by construction. A single-file, dependency-free module has no transitive version conflicts to resolve, and the version string is available from the module itself: the Makefile defines VERSION by running ./bottle.py --version. The pyproject.toml also declares a console script entry point named bottle mapped to bottle:main, so the package installs a command-line entry point as well as the library. This is not legal advice; read the LICENSE file in the repository before relying on either the code grant or the logo restriction.
Editorial conclusion
Adopt Bottle for small WSGI services, internal tools and apps that must ship as one file with no dependencies beyond the standard library. Do not adopt it if you want an ORM, an admin interface or a large plugin ecosystem; Bottle provides none of these. Before committing, check that your Python is at least 3.9, that your deployment target speaks WSGI (gunicorn, paste or cheroot are named in the README), and whether you need to serve static files, since the README documents none of that.
Frequently asked questions
What is Bottle in Python?
Bottle is a WSGI micro web-framework for Python, distributed as a single file module with no dependencies other than the standard library. It provides routing, a built-in template engine, HTTP utilities and a development server.
How do I install Bottle?
The README says to install the latest stable release with pip install bottle, or to download bottle.py into your project directory. The download option is marked unstable because it tracks the main branch rather than a release.
How do I start a Bottle server?
Call run() after defining your routes. The README's example uses run(host='localhost', port=8080) and then directs the browser to http://localhost:8080/hello/world. That starts the built-in development server.
Which Python versions does Bottle support?
The pyproject.toml sets requires-python to ">=3.9", so Bottle requires Python 3.9 or newer.
What licence does Bottle use?
The code and documentation are available under the MIT License. The README states that the Bottle logo is not covered by that licence and may be used as a link to the homepage or in direct context with the unmodified library.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/bottlepy-bottle)Star history chart for your README
[](https://hysenlabs.com/projects/bottlepy-bottle)Was this useful?