Registry / web-framework / bottle

bottle

JSON →
library0.13.4pypypi✓ verified 8d ago

Bottle is a fast, lightweight, and simple WSGI micro-framework for small web-applications. It provides routing, templating, and basic utilities in a single file, making it ideal for prototyping and small services. The current stable version is 0.13.4, with releases occurring infrequently, often focusing on Python version compatibility and minor fixes rather than new features.

pip install bottle
INSTALL
IMPORT
SIG · BOTTLE
B
bottle
web-frameworkpythonv0.13.4
Install
1.6s avg
Import
125ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.13.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.130s · 18.1MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.120s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

route
from bottle import route
Decorator for defining HTTP routes.
run
from bottle import run
Function to start the development server.
request
from bottle import request
Thread-local proxy to the current request object.
response
from bottle import response
Thread-local proxy to the current response object.
template
from bottle import template
Function to render templates (e.g., SimpleTemplate, Mako, Jinja2).

This quickstart defines a simple route that takes a name parameter and renders a basic HTML template using Bottle's built-in `SimpleTemplate` engine. It then starts a development server on `127.0.0.1:8080`. Note the explicit host for `run()` due to changes in Bottle 0.13.

from bottle import route, run, template @route('/hello/<name>') def index(name): return template('<b>Hello {{name}}</b>!', name=name) # For development, specify host explicitly due to 0.13 change # For production, use a WSGI server like Gunicorn or uWSGI if __name__ == '__main__': run(host='127.0.0.1', port=8080)
Debug
Known issues
breakingBottle 0.13 dropped support for Python 2.x and older Python 3.x versions (3.4, 3.5, 3.6). Projects upgrading to 0.13 or newer must use Python 3.7 or higher.
fix
Ensure your project's Python interpreter is version 3.7 or newer before upgrading to Bottle 0.13.x.
affects: 0.13.0+
breakingThe default host for `bottle.run()` changed from `0.0.0.0` (all interfaces) to `127.0.0.1` (localhost only) in version 0.13 for security reasons. This affects how your development server is accessible.
fix
If you need your development server to be accessible from other machines, explicitly specify `host='0.0.0.0'` in your `run()` call (e.g., `run(host='0.0.0.0', port=8080)`).
affects: 0.13.0+
gotchaBottle's `request` and `response` objects are thread-local proxies. Attempting to access them outside of an active request context (e.g., at module level) will result in a `RuntimeError`.
fix
Always access `request` and `response` within route handlers or functions called from within a handler where a request context is active. Do not try to store or access them globally outside of a request.
affects: All versions
gotchaThe `bottle.run()` function is intended solely for development and testing. It uses a simple, single-threaded server and is not suitable for production deployments due to performance, reliability, and security concerns.
fix
For production environments, deploy your Bottle application with a robust WSGI server such as Gunicorn, uWSGI, or CherryPy.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'bottle'
The 'bottle' library is not installed in the Python environment being used, or the Python interpreter cannot find it due to an incorrect `PYTHONPATH` or virtual environment not being activated.
fix
Install the bottle library using pip: `pip install bottle` or `pip3 install bottle` if you have multiple Python versions. Ensure your virtual environment is active if you are using one.
Template 'my_template.tpl' not found
Bottle cannot find the specified template file. This often happens because the template file is not in the expected directory, or the `bottle.TEMPLATE_PATH` is not correctly configured, especially when deploying or running the application from a different working directory.
fix
Ensure the template file exists at the specified path relative to where your Bottle application is run. You can explicitly add template directories to Bottle's search path using `bottle.TEMPLATE_PATH.insert(0, '/path/to/your/templates')` or use an absolute path.
AttributeError: 'Bottle' object has no attribute 'template'
This error occurs when trying to call `template()` as a method of a `Bottle` application instance (e.g., `app.template(...)`) instead of using the global `bottle.template()` function, or importing `template` directly from the `bottle` module.
fix
Call the `template` function directly from the `bottle` module: `from bottle import template` and then `template('my_template', **kwargs)` or `bottle.template('my_template', **kwargs)` if not imported directly.
Error: 404 Not Found
The requested URL does not match any defined route in the Bottle application. This can be due to a typo in the URL, incorrect route definitions (e.g., missing a dynamic part, wrong HTTP method), or issues with how the application is mounted in a WSGI server.
fix
Verify the URL being accessed matches a defined `@route()` decorator. Check for typos in the URL or route string, ensure the HTTP method (GET, POST, etc.) is correct, and if using dynamic routes, confirm the syntax (e.g., `<name:int>`). If deployed with WSGI, verify the application's base path.
TypeError: wsgi_app() takes 0 positional arguments but 2 were given
This error typically occurs when deploying a Bottle application with a WSGI server (like Gunicorn). The WSGI specification requires the callable application to accept two arguments (`environ` and `start_response`), but the Bottle application (or a wrapper function) is defined without them.
fix
Ensure your WSGI entry point function correctly accepts the `environ` and `start_response` arguments, even if it just delegates to `bottle.default_app()`. For example, `def wsgi_app(environ, start_response): return bottle.default_app()(environ, start_response)`. Or, if using an application factory pattern, call the factory with `gunicorn 'app:wsgi_app()'`.
Upgrade
Version history
0.13.4latest on PyPI · released Jun 15, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
31 hits · last 30 days
node
30
Resources
bottle — pip install bottle · libregistry