Getting Started
Welcome! This guide will help you set up your development environment using this Python template. You'll be up and running in just a few minutes.
Prerequisites
Before you begin, you'll need to install the following tools on your machine:
- Docker Desktop - Container platform for running the development environment
- Visual Studio Code - Code editor with excellent Python support
- Dev Containers Extension - VSCode extension for container-based development
Setup Options
You have three ways to set up your development environment. Choose the one that best fits your workflow:
Option 1: Dev Container (Recommended)
The Dev Container approach provides a fully configured, consistent development environment that works the same on any machine.
Pros:
- ✅ Zero configuration - everything is pre-configured
- ✅ Consistent across all team members
- ✅ Isolated from your host system
- ✅ All dependencies included
- ✅ Pre-installed VSCode extensions
Setup steps:
- Install Docker Desktop
- Install VSCode and the Dev Containers extension
- Clone this repository
- Open the folder in VSCode
- Click "Reopen in Container" when prompted
That's it! Your environment is ready to use.
Option 2: Docker Only
If you prefer to use Docker without VSCode integration, you can use the standalone Docker setup.
Pros:
- ✅ Works with any editor
- ✅ Consistent environment
- ✅ Easy to integrate with CI/CD
Setup steps:
1 2 3 4 5 6 7 8 9 10 11 12 13 | |
Option 3: Local Installation
For advanced users who prefer to work directly on their host machine.
Pros:
- ✅ No Docker overhead
- ✅ Direct access to system resources
- ✅ Faster startup times
Requirements:
- Python 3.11 or higher
- uv package manager
Setup steps:
1 2 3 4 5 6 7 8 9 10 11 12 | |
Verify Your Setup
Once your environment is set up, verify that everything is working:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | |
If all commands complete successfully, you're ready to start developing! 🎉 See Task Automation with nox for all sessions and flags.
Detailed Setup Guides
For step-by-step instructions with screenshots, see the detailed guides:
- Docker Setup Guide - Install Docker Desktop on your platform
- VSCode Setup Guide - Configure Visual Studio Code
- Dev Container Guide - Set up the Dev Container extension
Troubleshooting
Ruff formatting not working in VSCode
If Ruff formatting doesn't activate automatically:
- Press
Cmd+Shift+P(macOS) orCtrl+Shift+P(Windows/Linux) - Type "Developer: Reload Window"
- Press Enter
This reloads the VSCode window and should activate the Ruff extension.
Docker container won't start
Make sure Docker Desktop is running:
- macOS: Check for the Docker icon in your menu bar
- Windows: Check for the Docker icon in your system tray
- Linux: Run
sudo systemctl status docker
Permission errors with Docker
On Linux, you may need to add your user to the docker group:
1 | |
Log out and log back in for the changes to take effect.
Using as a Template
When you start a new project from this template:
- Update the project name and description in
pyproject.toml(see Customizing for Your Project). - Add project-specific configuration by extending
Settings(see Extending Settings). - Use the utilities in
tools/, or remove them if you do not need them. If you remove or add packages, updateincludeinty.toml(see ty Configurations). - Put shared defaults in
.env.local(committed) and secrets in.env(not committed) (see Environment Files). - Customize Ruff rules in
ruff.tomlonly when needed (see Ruff Configurations).
Next Steps
Now that your environment is set up, explore the guides to learn how to use the tools:
- Development Guides - Learn how to use uv, Ruff, pytest, and more
- Built-in Utilities - Explore the logger, config, and tracer modules
- Configuration Reference - Understand tool configurations
- Use Cases - See practical examples (Jupyter, FastAPI, OpenCV)