A professional Python project template that always uses portable Python - never relies on system installations.

• 🎯 Always Portable - Consistent Python environment everywhere
• 📦 Self-Contained - No dependency on system Python
• 🔄 Reproducible - Same exact Python version every time
• 🚀 Distributable - Package includes everything needed

# 1. Clone or use this template git clone https://github.com/yourusername/your-project cd your-project # 2. Run setup (downloads Python 3.13.9 first time, ~2 minutes) ./setup.sh # 3. Activate and run source .venv/bin/activate python src/main.py

That's it! No system Python needed.

your-project/ ├── .github/ │ └── workflows/ │ └── ci.yml # CI/CD pipeline ├── .python/ # Portable Python 3.13.9 (~80MB, gitignored) ├── .venv/ # Virtual environment (gitignored) ├── src/ │ ├── __init__.py │ └── main.py ├── tests/ │ ├── __init__.py │ └── test_main.py ├── .gitignore ├── CONTRIBUTING.md # Contribution guidelines ├── pyproject.toml # Project configuration ├── README.md ├── QUICK_REFERENCE.md ├── setup.sh # Setup script ├── uv.lock └── verify-python-version.sh # Version checker 

# Setup (first time downloads Python, subsequent runs reuse it) ./setup.sh # If something breaks, clean rebuild ./setup.sh --force-clean # Add a dependency # 1. Edit pyproject.toml # 2. Then: uv lock uv sync 

1. Downloads pre-built Python 3.13.9 from python-build-standalone
2. Installs to .python/ directory
3. Creates virtual environment in .venv/
4. Installs dependencies with UV

1. Finds existing .python/ installation
2. Reuses it (no download needed!)
3. Creates fresh .venv/
4. Installs dependencies

1. Deletes .python/, .venv/, uv.lock
2. Downloads Python 3.13.9 again
3. Fresh installation

• .python/ : ~80 MB (one-time)
• .venv/ : ~50 MB (varies by dependencies)
• Total: ~150 MB uncompressed
• Package: ~50 MB compressed

Small price for complete portability!

# Day 1: Setup ./setup.sh source .venv/bin/activate # Daily development python src/main.py pytest # Add dependencies # Edit pyproject.toml, then: uv lock && uv sync # If weird issues ./setup.sh --force-clean

# 1. Ensure clean build ./setup.sh --force-clean # 2. Test your app source .venv/bin/activate python src/main.py

Edit setup.sh:

PYTHON_VERSION="3.14.*" # Or any version

Available versions: https://github.com/indygreg/python-build-standalone/releases

# Virtual environment issues rm -rf .venv/ && ./setup.sh # Complete fresh start ./setup.sh --force-clean # Check what you have .python/bin/python3 --version source .venv/bin/activate && python --version

• Setup Guide - Detailed guide
• Quick Reference - Command cheat sheet
• UV Documentation

Portable Python is OS and architecture specific:

• ✅ macOS x86_64 → macOS x86_64
• ✅ macOS arm64 (M1/M2/M3) → macOS arm64
• ✅ Linux x86_64 → Linux x86_64
• ✅ Linux aarch64 → Linux aarch64
• ❌ macOS → Linux (use Docker)
• ❌ x86_64 → arm64 (use Docker)
• ❌ Windows (use WSL or Docker)

This project follows Conventional Commits for clear and structured commit history.

Format:

<type>(<scope>): <description> [optional body] [optional footer] 

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, no logic change)
• refactor: Code refactoring (no feature change or bug fix)
• perf: Performance improvements
• test: Adding or updating tests
• chore: Maintenance tasks (dependencies, config)
• ci: CI/CD changes

Examples:

feat(setup): add Python 3.14 support fix(package): correct tar.gz extraction path docs(readme): update installation instructions chore(deps): upgrade uv to latest version refactor(setup): improve error handling

Scope (optional): Component affected (setup, package, docs, etc.)

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with conventional commits
4. Run tests and linting (pytest && black --check .)
5. Update documentation if needed
6. Commit your changes (git commit -m 'feat: add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request with:
   • Clear description of changes
   • Link to related issues
   • Screenshots/examples if applicable

• Python Code: Follow PEP 8, use Black formatter
• Bash Scripts: Use ShellCheck for validation
• Documentation: Clear, concise, with examples
• Tests: Add tests for new features

# Format code black src/ tests/ # Run linting flake8 src/ tests/ # Run tests pytest tests/ # Verify script works ./setup.sh --force-clean

# Use the included commit message template git config commit.template .gitmessage # Now when you commit, you'll see helpful hints git commit

See CONTRIBUTING.md for detailed guidelines.

MIT License - See LICENSE file

• python-build-standalone - Pre-built Python distributions
• UV - Fast Python package installer
• Built with modern Python best practices

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

⭐ If you find this template helpful, please star it!

Ready to use? Click "Use this template" above or clone and start building!