lithium documents three install paths, and two of them install different dependency sets

Two dependency lists, and they do not agree

There are two places in this repository that declare what to install, and they are not the same list.

The project manifest is the modern one. It names the project, sets a version, requires a minimum Python, and declares seven runtime dependencies using compatible-release ranges: the framework itself, the authentication package with two extras enabled, the debug toolbar, a bootstrap-flavoured forms package, a production server, a PostgreSQL driver with its binary distribution, and the static file server. One development dependency sits in a separate group.

The requirements file is the older one. It carries twenty-five exact pins, the great majority of them transitive: the HTTP stack, the cryptography library, a JSON schema parser, the OpenID and JWT libraries, the certificate bundle and its dependencies.

The overlap is not complete. One package the feature list names for form handling appears in the requirements file and not in the manifest, because the manifest names the bootstrap wrapper instead. So the pip path installs a package the fast path does not.

That is the practical consequence, and it is the first thing to check if you plan to move between the two. It also means the two paths have different reproducibility properties. A lock file is committed for the fast path, so that one resolves identically on every machine. The requirements file has exact pins but no hashes, so it is reproducible in version and not in content.

Three Python versions appear in three places

The version story is small but inconsistent, and it is the kind of thing that wastes an afternoon for someone whose distribution ships an older interpreter.

The feature list opens with the framework version and a Python version, and names Python 3.13. The project manifest requires 3.12 or newer. The container image is built on 3.12.

So the manifest's floor is the oldest of the three and the advertised version is the newest. Nothing is contradictory in itself: a project can support 3.12 and newer and be developed against 3.13. But it does mean the advertised number is not the requirement, and a reader who trusts the feature list will install the wrong thing on a machine with 3.12 and assume something else is wrong.

The manifest's own version field is worth noting alongside this. It reads 0.1.0, and the project has been renamed and pushed to for well over a year, so the version in the manifest is not tracking releases. The platform shows no releases at all for this repository, so there is no tag to cite either.

The tree is a conventional application layout: a management script at the root, a settings project, two application directories for accounts and pages, plus static files, templates, a container file and a compose file. There is no packaging metadata for a distributable library, which is right for a starter project and another sign the version field is decorative.

The Docker path needs a settings edit before anything runs

Two of the three documented install paths are two commands and a clone. The third is not, and the difference is worth understanding.

For the container path you are told to update the database section of the settings file to point at a PostgreSQL engine, with a name, a user and a password all set to the same literal word, and a host of a single service name that a comment attributes to the compose file, on the default port. That is a hand-written dictionary you paste over whatever is there.

Then you are told the allowed-IP setting for the debug toolbar must also be updated, with a snippet that resolves the machine's hostname to a list of addresses and then rewrites the last character of each one to the digit one. That is a container-address assumption baked into your settings file, and it exists only so the debug toolbar will accept requests from inside the container.

The snippet's own comment names a different settings path than the prose immediately above it. Two paths, one file, in consecutive sentences.

And then the security observation. The compose file sets the database's authentication method to trust, which means the database accepts any connection without checking a password. The password in the dictionary you were told to paste in is therefore decorative. Combined with the web port being published without a bind to the loopback address, the container as shipped is a development convenience, and nothing in the readme says so.

The image serves production, the compose file replaces it with development

The container file is the most carefully built artifact in the repository, and then the compose file overrides most of what it is for.

The build is two stages. The first uses the official tool image for the resolver's runtime, compiles bytecode at install time, and forces copy mode for links. It uses bind mounts for the lock file and the manifest, then syncs with the lock frozen, the project itself not installed and no development group. Then it adds the source and syncs again, this time with the project installed. That two-step order is the standard way to keep the dependency layer cached when only your own code changes.

The second stage drops the resolver entirely and uses a plain slim interpreter image. It copies the built tree with ownership set to an unprivileged user, disables bytecode writing and unbuffered output, and puts the virtual environment's binary directory on the path. The default command runs a production server, two workers, bound to a port, against the WSGI application.

The compose file then replaces that command with the development server bound to all interfaces, and mounts the entire repository at a path inside the container that is not the path the image uses. So depending on how you run it, your source is at one root or the other, and the server is either a production worker pool or a development server. Both are reasonable; having them disagree in the same repository without saying so is the problem.

The feature list and the manifest name different forms packages

Reading the feature list against the dependency declarations turns up a few places where the two describe different projects.

Forms are the clearest. The feature list credits a forms package by one name; the manifest declares a bootstrap-flavoured wrapper of that package, and the requirements file pins both. Nobody is wrong, but a reader looking for the package the features promised will not find it under that name.

Social authentication is the second. The manifest enables the extras for OpenID and social accounts, so they are installed by default on both paths. The feature list promises only logging in, signing up and password reset, and social authentication appears later in the next-steps list as something to add if needed. It is already there.

The debug toolbar is the third. It is a shipped feature and a default dependency, and under the container path it is also the reason you have to edit a setting in your source before the application will start.

One more inversion worth naming. Password reset is listed as a shipped feature, while the email backend is listed as a next step with a mail provider to connect. So the reset flow ships before the thing it needs to send mail.

And there is no PostgreSQL in the feature list at all, though the container path requires it and the manifest carries its driver, which suggests the default local path is a file-backed database and the database driver is there for the container.

The next-steps list is also the punchline

After the feature list there is a short to-do section, and it reads less like optional polish and more like an admission of what is not finished.

It asks you to add environment variables, and states a personal preference for one particular settings library rather than naming a constraint. The next-steps section has one more version of that disagreement, because the production server is a declared dependency and also a thing you are asked to add. It asks you to update the email backend and connect a provider, without which the shipped password reset cannot send anything. And it asks you to make the admin more secure, with a link to an article about it.

The pip path, for comparison, is four commands and needs nothing edited:

(.venv) $ pip install -r requirements.txt
(.venv) $ python manage.py migrate
(.venv) $ python manage.py createsuperuser
(.venv) $ python manage.py runserver

That last one deserves a note rather than a pass. A starter project ships the Django admin enabled, and the readme's own list tells you that hardening it is a thing you should do later, with a link to someone else's write-up. It is honest, and it is also a list of production concerns that a project copied without reading will inherit.

The section closes by saying these steps are all covered in tutorials and premium courses elsewhere. So the gap between what the boilerplate does and what you need for production is acknowledged, and the walkthrough of it is the business.

The support section asks for a star if the project helped, which is the only ask in the readme that is not about installing anything.

The rename left a description and a branch name behind

This project was renamed in November 2024 from a different name, and the readme says so in one line. The rename is visible in three places it has not finished.

The repository's one-line description still says it is a Django starter project under the framing of the old name, complete with an emoji, which is not what a search result should say about a project that has a new name.

The contributing link points at a file path that begins with a branch named master, while the repository's default branch is main. On a platform where master is not the default, that link resolves to a 404 for anyone who has not kept an old branch around. It is the kind of leftover that only a project which has changed both its name and its branch convention would have.

There is a third, smaller one in the install section. The feature list links the fast Python environment tool by pointing at its source repository on a code host, while the section below it links the same tool's own documentation site. One of those is where a user should end up.

And there is no test directory among the top-level entries, and no test configuration. For a boilerplate whose next-steps list is a production checklist, that is the most consequential absence in the repository, because it is the one nobody inherits by accident.

Editorial conclusion

This is worth starting from if you want a Django project with authentication, static files, forms and error pages already wired, because the assembly work is real and this saves an afternoon. Three things to know before you build on it. Pick one install path and commit to it, because the fast path and the pip path do not install the same packages and only one of them is locked to a file in the repository. Treat the Docker path as requiring a settings edit before anything runs, and check the database authentication setting in the compose file before you put it anywhere reachable. And read the next-steps list as a to-do rather than as optional, because the mail backend that password reset depends on is on it, as is hardening an admin that ships enabled.

Frequently asked questions

Official sources

1. Issues
2. README
3. wsvincent/lithium on GitHub