Python project setup instructions

python_project_setup.md

Python Project Setup Guide

This guide walks through setting up a new Python project using mise for Python version management, uv for fast dependency management, and pyproject.toml for project configuration.

Prerequisites

• mise installed on your system
• uv installed on your system
• Basic familiarity with Python and virtual environments

Step-by-Step Setup

1. Create Project Directory

mkdir my-project
cd my-project

2. Create .mise.toml Configuration

Create a .mise.toml file in your project root to specify the Python version:

[tools]
python = "3.12"  # or your preferred version

3. Trust and Install mise Configuration

mise trust
mise install

This will install the Python version specified in your .mise.toml file.

4. Create Virtual Environment with uv

uv venv

This creates a .venv directory with your virtual environment.

5. Activate Virtual Environment

source ./.venv/bin/activate

You should see (.venv) appear in your terminal prompt, indicating the virtual environment is active.

6. Create pyproject.toml

Create a pyproject.toml file for your project configuration:

[project]
name = "my-project"
version = "0.1.0"
description = "A brief description of your project"
requires-python = ">=3.12"
dependencies = [
    # Add your runtime dependencies here
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

7. Sync Dependencies with uv

uv sync

This will:

• Read your pyproject.toml
• Create a uv.lock file with pinned versions
• Install all dependencies (including dev dependencies) into your virtual environment

If you want to sync without dev dependencies:

uv sync --no-dev

Quick Reference

Once your project is set up, here's the typical workflow:

# Enter project directory
cd my-project

# Activate virtual environment
source ./.venv/bin/activate

# Sync dependencies (updates based on pyproject.toml)
uv sync

# Add a new dependency
uv add requests

# Add a dev dependency
uv add --dev pytest-cov

# Remove a dependency
uv remove requests

# Run your code
python your_script.py

# Deactivate when done
deactivate

Adding Dependencies

To add a new dependency, you have two options:

Option 1: Using uv add (recommended)

uv add package-name

This will automatically update your pyproject.toml and uv.lock file.

Option 2: Manual edit

1. Add it to the dependencies array in pyproject.toml
2. Run uv sync to install it

.gitignore

Don't forget to create a .gitignore file:

.venv/
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
dist/
*.egg-info/

# Note: uv.lock should typically be committed to track exact versions
# Only add it to .gitignore if you have a specific reason not to commit it

Additional Resources

• uv documentation
• mise documentation
• pyproject.toml specification
• Python Packaging User Guide