PyCaret 4.0: two containers, one volume, one unrecoverable password

One api container runs the backend, the scheduler, the compute and the database

The compose file ships two containers, and one of them has four jobs. The api service builds from infra/docker/Dockerfile.api, publishes ${PYCARET_API_PORT:-8020}, mounts the named volume pycaret-data at /data, and inside that single FastAPI process runs SQLAlchemy, APScheduler as an in-process worker for V1, the compute itself, and SQLite at the default PYCARET_DATABASE_URL of sqlite:////data/pycaret.db with artifacts written to /data/artifacts. The web container does less: nginx serves a built React bundle and proxies /api and /ws back to api. The project frames this as the same single-binary shape Plausible, Vaultwarden and n8n use for self-hosters, good on a laptop and fine for a small team. The stated intent is that every external dependency, storage, DB, secrets, auth, queue and compute, sits behind a Protocol with multiple implementations, so the same codebase can later target separate api, worker and runtime containers on RDS, S3, SecretsManager, SQS and Fargate. Most of those Protocol extractions are still ahead, and docs/revamp/PLATFORM_ARCHITECTURE.md carries the gap matrix. The consequence: there is no scaling story for the scheduler or the compute today, because there is nothing separate to scale out to.

A laptop first build stalls at pip install when Docker is short of RAM

The prerequisites are Docker Desktop 4.27+, or Docker Engine 25.0+ with Compose v2.24+, and the entry point is three lines:

git clone https://github.com/pycaret/pycaret.git
cd pycaret
docker compose up --build

The first build takes about five minutes across Python dependencies, npm install and the Vite build, and later starts land under thirty seconds. You know it is ready when the api log shows pycaret-api with INFO: Application startup complete. and the web log shows nginx starting, then http://localhost:3020 opens on a setup screen that asks for the first admin account and workspace. On a laptop, that first build is where it goes wrong, and both documented failures are capacity rather than correctness. A build sitting at pip install for more than ten minutes means a slow network or a RAM starved Docker Desktop, and the fix is Docker Desktop, Settings, Resources, at least 6 GB of RAM. A no space left on device error means old images, and the fix is:

docker system prune -a

A port clash on 3020 or 8020 has its own override, PYCARET_WEB_PORT=3030 PYCARET_API_PORT=8030 docker compose up, and there is a separate escape hatch for Windows checkouts that picked up CRLF endings: git clone --config core.autocrlf=false.

A fresh volume answers every /api call with 404 until Alembic finishes

The web UI can be serving before the backend can answer a request, and the troubleshooting table names that exact case: the interface loads but every /api call returns 404, the cause is that pycaret-api has not finished bootstrapping through its Alembic migrations, and it happens on the very first up against an empty volume. The fix is to wait about thirty seconds for the health check and to watch it happen with docker compose logs -f api. The consequence lands on automation rather than on a human at a browser, because a smoke test or CI job that fires requests as soon as the port is open will fail on the first run of a fresh volume and pass on every run afterwards. That is the worst shape for a flaky test, since the failure is real but only ever reproduces once per machine. Gate your first requests on the health check or on the startup log line rather than on port availability, and expect the same delay again after any operation that recreates the volume.

The published default JWT secret is still sitting in .env.example

Access and refresh tokens are signed with PYCARET_JWT_SECRET, and the value that ships is one that announces itself. Copying the template to .env leaves you with the dev-only default (dev-only-jwt-secret-do-not-use-in-prod) unless you edit it, and .env is gitignored, so nothing warns you that the edit did not happen:

cp .env.example .env
# edit .env: set PYCARET_JWT_SECRET to something real, etc.
docker compose up

The template's own note on that variable is to treat losing or leaking it the same as losing every user's password, and the compose defaults fall back to a development value when the variable is absent. The consequence of shipping the default is concrete: every token your instance issues is signed with a string that exists in a public repository, which means anyone can mint a token that validates. This is the one variable the project marks as having to be a strong random value in any production deploy, and it is also the one most likely to be skipped.. The Fernet key can be generated by hand if you want to manage it yourself:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

The Fernet key lives on the same volume as the data it decrypts

PYCARET_SECRETS_KEY is a Fernet key used to encrypt LLM API keys and datasource passwords at rest. Left blank, which is the default in the template, the api container generates one on first start and persists it to the data volume. That is the right behaviour for a laptop and a problem the moment you run more than one process: the instructions are to set the variable explicitly only when you want the same key across multiple instances, such as multi-replica or blue/green. Without that, each instance auto-generates its own key. The same coupling decides whether a backup is worth anything at all. The named volume holds the SQLite database, uploaded CSVs, fitted .pkl files and the Fernet key together, so restoring the database file without the matching key leaves you with rows you cannot decrypt. Take the whole volume or take nothing.

docker compose down -v is the only way back from a lost admin password

The documented credential-recovery path deletes your data. The troubleshooting row for a forgotten admin password says the database is encrypted, that you cannot recover it, and that the fix is docker compose down -v to wipe and re-bootstrap. The two shutdown commands are where the difference sits: docker compose down stops the containers and preserves the volume, so the database and the key survive, while docker compose down -v wipes everything including that volume. The consequence is that an instance becomes unrecoverable the moment an operator forgets a credential, and the supported remedy costs you every experiment, run, uploaded CSV and fitted model in the volume. Treat access control to the setup screen as the real security boundary, not the bridge.

Installing pycaret from PyPI gives you the frozen 3.x line, not this repo

The code in this repository and the package on PyPI are different lines, and the version numbers make that easy to miss. The 3.x line is frozen on PyPI as pycaret 3.4.0 with no further commits, while main carries the 4.0 line, which the README marks as work in progress. The releases under that banner are alphas: v4.0.0a0 and v4.0.0a1, both from April 2026, and the last 3.x release listed is 3.3.2 from April 2024. So anyone reaching for pycaret on PyPI gets the frozen 3.x API rather than the container platform described here, and there is no stable 4.0 release to pin. The consequence for a team choosing between them is that you are picking a documented, frozen library you can depend on, or a compose stack whose newest tagged build is an alpha from six months ago whose last push to main was on 2026-07-23. If you take the 4.0 line, track docs/revamp/STATUS.md and docs/revamp/ROADMAP.md for the gap between what the README promises and what ships, and read docs/revamp/PLATFORM_ARCHITECTURE.md before assuming a Postgres or S3 deployment is a config change rather than unfinished work.

The root pyproject lints the new surface and excludes code marked for deletion

The root pyproject.toml is not a project definition, and reading it as one misleads you. It declares a uv workspace with two Python members, packages/engine and services/api, maps pycaret and pycaret-server onto the workspace through tool.uv.sources, and says in a comment that the name pycaret is published from packages/engine/pyproject.toml with no single monolithic package at the repo root anymore. The lint configuration is where the 4.0 status shows up a second time. Ruff runs with line-length 100 and target-version py313 and selects E, F, I, UP and B while ignoring E501 and E731, but the exclude list drops packages/engine/pycaret/internal, packages/engine/pycaret/containers, the oop.py file in classification, regression, clustering, anomaly and time_series/forecasting, plus datasets.py and utils. The stated reason in the file is that those are legacy code paths scheduled for a Phase 5 drain, that linting code destined for deletion creates noise, and that lint is enforced on the new 4.0 surface only. The consequence: a clean ruff run in this repository says nothing about those modules, and a contributor can break style in code that still executes without ruff objecting.

Editorial conclusion

PyCaret 4.0 suits a team that wants a self-hosted AutoML interface it can run on one host and is willing to treat the compose file as the product. It does not suit anyone who needs multi-replica storage, a recoverable admin credential, or a stable release to pin, since the newest tags are April 2026 alphas on a branch marked work in progress. Before adopting it, back up the entire pycaret-data volume rather than the database alone, and set PYCARET_JWT_SECRET and PYCARET_SECRETS_KEY yourself.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. pycaret/pycaret on GitHub
4. README
5. Releases