BaseUser is a Table you can use to store and authenticate your users.

Creating the Table

Run the migrations:

piccolo migrations forwards user


The app comes with some useful commands.

user create

Creates a new user. It presents an interactive prompt, asking for the username, password etc.

piccolo user create

If you’d prefer to create a user without the interactive prompt (perhaps in a script), you can pass all of the arguments in as follows:

piccolo user create --username=bob --password=bob123  --is_admin=t --is_superuser=t --is_active=t

If you choose this approach then be careful, as the password will be in the shell’s history.

user change_password

Change a user’s password.

piccolo user change_password

user change_permissions

Change a user’s permissions. The options are --admin, --superuser and --active, which change the corresponding attributes on BaseUser.

For example:

piccolo user change_permissions some_user --active=true

The Piccolo Admin (see Ecosystem) uses these attributes to control who can login and what they can do.

  • active and admin - must be true for a user to be able to login.
  • superuser - must be true for a user to be able to change other user’s passwords.

Within your code


To check a user’s credentials, do the following:

from piccolo.apps.user.tables import BaseUser

# From within a coroutine:
>>> await BaseUser.login(username="bob", password="abc123")

# When not in an event loop:
>>> BaseUser.login_sync(username="bob", password="abc123")

If the login is successful, the user’s id is returned, otherwise None is returned.

update_password / update_password_sync

To change a user’s password:

# From within a coroutine:
await BaseUser.update_password(username="bob", password="abc123")

# When not in an event loop:
BaseUser.update_password_sync(username="bob", password="abc123")


Don’t use bulk updates for passwords - use update_password / update_password_sync, and they’ll correctly hash the password.