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, Pyrefly, and Nox configured out-of-the-box
- 📦 Dependency management - Fast, reliable dependency resolution with uv
- 🧹 Code quality - Automatic formatting and comprehensive linting
- ✅ Type checking - Static analysis with Pyrefly
- 🧪 Testing framework - Nox sessions for isolated test environments
- 📝 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)
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/
# Initialize a new git repository
git init
git add .
git commit -m "Initial commit from pylerplate"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 Pyrefly settings as needed
make help # Show all available commands
make format # Format code with Ruff
make lint # Run static analysis (Ruff + Pyrefly)
make test # Run tests with Nox
make build # Build distribution packages
make clean # Remove build artifacts and cachesIf you prefer not to use Make:
# Format code
ruff format
# Lint code
ruff check
pyrefly check
# Run tests
nox
# Build distribution
uv buildpylerplate/
├── src/
│ └── mypackage/ # Main package directory
│ └── __init__.py
├── tests/ # Test directory
│ └── __init__.py
├── Makefile # Task automation
├── noxfile.py # Nox test sessions
├── pyproject.toml # Project configuration
├── LICENSE # Project license
└── README.md # This file
This boilerplate uses Nox for testing, which creates isolated virtual environments for each test session:
# Run all test sessions
make test
# Or run specific sessions
nox -s lint # Run linting only
nox -s typing # Run type checking only| Tool | Purpose | Documentation |
|---|---|---|
| uv | Fast Python package installer and resolver | docs |
| Ruff | Extremely fast Python linter and formatter | docs |
| Pyrefly | Modern type checker for Python | docs |
| Nox | Flexible test automation | docs |
| Make | Task automation and workflow management | tutorial |
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 help target implementation
- The teams behind uv, Ruff, Pyrefly, and Nox for their excellent tools
If you encounter issues or have questions:
Happy coding! 🚀