Skip to content

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:

  1. Docker Desktop - Container platform for running the development environment
  2. Visual Studio Code - Code editor with excellent Python support
  3. 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:

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:

  1. Install Docker Desktop
  2. Install VSCode and the Dev Containers extension
  3. Clone this repository
  4. Open the folder in VSCode
  5. 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
# Clone the repository
git clone https://github.com/a5chin/python-uv.git
cd python-uv

# Build the Docker image
docker build -t python-uv .

# Run the container
docker run -it --rm -v $(pwd):/workspace python-uv

# Inside the container, install dependencies
uv sync

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.10 or higher
  • uv package manager

Setup steps:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/a5chin/python-uv.git
cd python-uv

# Install dependencies
uv sync

# Install pre-commit hooks (optional but recommended)
uv run pre-commit install

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
# Check uv is available
uv --version

# Install dependencies
uv sync

# Run tests
uv run nox -s test

# Format code
uv run nox -s fmt

# Run linters
uv run nox -s lint -- --pyright --ruff

If all commands complete successfully, you're ready to start developing! 🎉

Detailed Setup Guides

For step-by-step instructions with screenshots, see the detailed guides:

Troubleshooting

Ruff formatting not working in VSCode

If Ruff formatting doesn't activate automatically:

  1. Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
  2. Type "Developer: Reload Window"
  3. 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
sudo usermod -aG docker $USER

Log out and log back in for the changes to take effect.

Next Steps

Now that your environment is set up, explore the guides to learn how to use the tools: