Piccolo Admin

1.13.0 · active · verified Thu Apr 16

Piccolo Admin is a powerful and modern admin interface / CMS for Python, currently at version 1.13.0. It is built on top of the Piccolo ORM and works seamlessly with ASGI frameworks like FastAPI and Starlette. The library is actively maintained with regular updates, often coinciding with new releases of the core Piccolo ORM library.

Common errors

```
Unable to login to piccolo_admin
```
cause The `piccolo_admin.piccolo_app` is not registered in `APP_REGISTRY` in `piccolo_conf.py`, or database migrations for session authentication have not been applied, or no admin user has been created.

fix 1. Add `piccolo_admin.piccolo_app` to your `APP_REGISTRY`. 2. Run `piccolo migrations forwards all`. 3. Create an admin user via CLI: `piccolo user create`.
```
HTTP 500 error when trying to add/update rows in admin panel
```
cause This often occurs with complex table schemas where a required field is left empty, or there's a validation error, or a non-standard column name (e.g., camelCase) is causing parsing issues in the frontend or backend.

fix Check the server logs for detailed traceback. Ensure all required fields are populated. For complex schemas, consider creating custom forms using `FormConfig` for better control over validation and data handling.

Warnings

breaking Python 3.8 support was dropped in Piccolo Admin version 1.12.0. Users on Python 3.8 or older should upgrade their Python version to continue receiving updates.
Fix: Upgrade your Python environment to version 3.9 or higher.
gotcha An SVG loading vulnerability (GHSA-pmww-v6c9-7p83) in Piccolo Admin allowed for arbitrary access to admin page data and actions if SVG uploads were enabled.
Fix: Upgrade to Piccolo Admin version 1.3.2 or above. It's recommended to update to the latest version for all security patches.
gotcha For Piccolo Admin's session authentication to work correctly, `piccolo_admin.piccolo_app` must be added to the `APP_REGISTRY` in your `piccolo_conf.py` and database migrations must be run (e.g., `piccolo migrations forwards session_auth`).
Fix: Ensure `APP_REGISTRY` is configured and run `piccolo migrations forwards all` to apply necessary database schemas, including `BaseUser`.
gotcha Issues can arise when adding or editing rows for tables with complex schemas, especially with camelCase column names or non-default primary keys, which may prevent data from being saved correctly.
Fix: Review table schemas for problematic column names (prefer snake_case) and ensure primary key configurations are standard or handled through custom forms if necessary. Check GitHub discussions for specific workarounds.

Install

pip install piccolo-admin Base installation
pip install "piccolo-admin[fastapi,uvicorn]" With FastAPI and Uvicorn

Imports

create_admin
```
from piccolo_admin.endpoints import create_admin
```
The primary entry point for instantiating the admin interface.
FormConfig
```
from piccolo_admin.endpoints import FormConfig
```
Used for defining custom forms within the admin interface, often with Pydantic models.

Quickstart

This quickstart demonstrates how to run a local demo instance of Piccolo Admin, including a pre-configured database and sample data, using the `admin_demo` package. This allows you to quickly explore the features without writing any code.

# 1. Install Piccolo Admin with its demo dependencies:
pip install piccolo-admin admin_demo

# 2. Run the demo application:
python -m admin_demo

# 3. Open your browser to http://localhost:8000/admin/
#    Login with username: piccolo, password: piccolo123

view raw JSON →