Bootstrap a new Python project with best-practice tooling, runnable with a single command:
uvx pyptmpl my-projectIt scaffolds a fully-configured Python project.
- Runs
uv init --libto create the project skeleton - Writes an opinionated
pyproject.toml(CalVer, beartype, ruff, basedpyright, pyrefly, coverage) - Creates a smoke test under
src/<package>/tests/ - Creates a virtual environment via
uv venv - Creates
.gitignore,.yamllint, and.vscode/settings.json - Creates a single root
justfilewith quality, test, docs, and build recipes - Creates docs/build scaffolding (
docs/,docs_sphinx/,zensical.toml,build.spec) - Creates
.secrets.baselinealongside pre-commit config for detect-secrets - Optionally downloads a license from scancode-licensedb
- Optionally installs prek
and writes
.pre-commit-config.yaml(ssort, ruff, basedpyright, pyrefly, vulture, deptry, pip-audit, coverage-100, …) - Optionally generates GitHub Actions workflows
(lint-format, tests, typecheck, quality-security, publish-pypi,
docs, sphinx-api, github-release)
and
dependabot.yml - Runs
uv sync --extra dev --extra docs --extra buildby default to generateuv.lock
uvx pyptmpl [OPTIONS] [PROJECT_NAME]
positional arguments:
project_name Name of the new project (prompted if omitted)
options:
-h, --help show this help message and exit
-v, --version show program version and exit
-p VERSION, --python-version VERSION
Python version to target, e.g. 3.13 (prompted if omitted)
-d TEXT, --description TEXT
Short project description (prompted if omitted)
--no-license Skip the interactive license selection step
--no-prek Skip prek / pre-commit setup
--no-github-actions Skip GitHub Actions workflow generation
--no-sync Skip final uv sync/lockfile generation
# Fully interactive
uvx pyptmpl
# Supply all required values up front
uvx pyptmpl my-lib --python-version 3.13 --description "A cool library"
# Skip optional steps
uvx pyptmpl my-lib -p 3.13 -d "A cool library" --no-license --no-prek --no-github-actionspyptmpl keeps all its boilerplate in src/pyptmpl/templates/:
src/pyptmpl/templates/
├── pyproject.toml.tmpl # pyproject.toml skeleton
├── test_smoke.py.tmpl # smoke test
├── gitignore.tmpl # .gitignore entries
├── yamllint.tmpl # .yamllint config
├── vscode_settings.json.tmpl # .vscode/settings.json
├── justfile.tmpl # root justfile
├── pre-commit-config.yaml.tmpl # .pre-commit-config.yaml
├── typos.toml.tmpl # typos dictionary overrides
├── docs/index.md.tmpl # docs site landing page
├── docs/python-api.md.tmpl # API docs page
├── docs_sphinx/conf.py.tmpl # Sphinx configuration
├── docs_sphinx/custom.css.tmpl # Sphinx API styling
├── zensical.toml.tmpl # Zensical site config
├── build.spec.tmpl # PyInstaller spec template
├── github/dependabot.yml.tmpl
├── github/workflows/github-release.yml.tmpl
├── github/workflows/docs.yml.tmpl
├── github/workflows/lint-format.yml.tmpl
├── github/workflows/publish-pypi.yml.tmpl
├── github/workflows/quality-security.yml.tmpl
├── github/workflows/sphinx-api.yml.tmpl
├── github/workflows/tests.yml.tmpl
└── github/workflows/typecheck.yml.tmpl
Template variables use {{VARNAME}} syntax. Add or modify templates to customize
generated output for every new project.