A modern, minimal Python project boilerplate with batteries included
pylerplate eliminates the repetitive setup work when starting new Python projects. It comes pre-configured with modern development tools, sensible defaults, and a clean structure—giving you a solid foundation to build upon immediately.
- Modern Python tooling - uv, ruff, ty, tox, and pre-commit configured out-of-the-box
- Git Hooks - Automated pre-commit checks to ensure code quality before every commit
- Dependency management - Fast, reliable dependency resolution with uv
- Code quality - Automatic formatting and comprehensive linting
- Type checking - Static analysis with ty
- Testing framework - Tox environments for isolated test runs
- Standards compliant - Follows PEP standards and Python best practices
- Makefile automation - Common tasks accessible via simple make commands
- VSCode optimized - IDE settings included (works with any editor)
- Minimal configuration - Essential settings only, ready for customization
- Python 3.12 or higher
- uv (recommended) or pip
- make (optional, but recommended)
Complete these steps to make the boilerplate your own:
# Rename the package directory
mv src/mypackage src/yourpackage
# Find and replace throughout the codebase
# Search for: mypackage
# Replace with: yourpackage[project]
name = "yourpackage"
version = "0.1.0"
description = "Your project description"
authors = [{ name = "Your Name", email = "your.email@example.com" }]
keywords = ["keyword1", "keyword2"]Update the LICENSE file and copyright information:
- Replace
Copyright (c) 2023 oceordwith your copyright notice - Choose an appropriate license for your project
# Add runtime dependencies
uv add requests httpx
# Add development dependencies
uv add --dev pytest pytest-cov
# Or edit pyproject.toml directly- Search for
TODOcomments and address them - Review and update
README.md(replace this file) - Adjust ruff and ty settings as needed
Clone the repository and set up your new project:
# Clone and prepare your project
git clone https://github.com/oceord/pylerplate.git myproject
cd myproject
rm -rf .git/
# Perform the Customization Checklist
# Initialize a new git repository
git init
# Set up the virtual environment and install git hooks
make dev
# Commit the initial state
git add .
git commit -m "Initial commit from pylerplate"make help # Show all available commands
make format # Format source code
make check # Lint and static analysis
make test # Run tests (via Tox)
make build # Build distribution artifactsIf you prefer not to use Make:
# Format code
uvx ruff format
# Lint code
uvx ruff check
uvx ty check
# Run tests
uvx --with tox-uv tox
# Build distribution
uv buildpylerplate/
├── src/
│ └── mypackage/ # Main package directory
│ └── __init__.py
├── tests/ # Test directory
│ └── __init__.py
├── Makefile # Task automation
├── pyproject.toml # Project configuration
├── LICENSE # Project license
├── README.md # This file
└── tox.toml # Tox environments
This boilerplate uses Tox for testing, which creates isolated virtual environments for each environment:
# Run all environments
make test
# Or run specific environments
uvx --with tox-uv tox -e lint # Run linting only
uvx --with tox-uv tox -e py312-typecheck # Run type checking only| Tool | Purpose | Documentation |
|---|---|---|
| uv | Fast Python package installer and resolver | docs |
| ruff | Extremely fast Python linter and formatter | docs |
| ty | Modern type checker for Python | docs |
| tox | Flexible test automation | docs |
| pre-commit | Framework for managing and maintaining multi-language pre-commit hooks | docs |
| make | Task automation and workflow management | docs |
Use pylerplate if you:
- Want modern development tools configured immediately
- Need a quick Python environment for experimentation
- Value clean, organized project structure
- Follow engineering best practices and standards
- Prefer minimal but sensible defaults
Look elsewhere if you:
- Prefer older, more established tooling (setuptools, black, etc.)
Contributions are welcome! Whether you've found a bug, have a feature suggestion, or want to improve the boilerplate:
- Open an issue to discuss your idea
- Fork the repository and create a feature branch
- Submit a pull request with your improvements
Please ensure your contributions align with pylerplate's philosophy: modern, minimal, and practical.
Distributed under the MIT License.
See LICENSE for more information.
- AlexanderWillner for the elegant Makefile example
- The teams behind uv, ruff, ty, tox, and pre-commit for their excellent tools
If you encounter issues or have questions:
Happy coding!