setup-to-pyproject

simonw's avatarfrom simonw

Migrate Python projects from setup.py/setup.cfg to pyproject.toml for use with uv. Use when upgrading legacy Python packaging, converting setup.py to modern pyproject.toml format, setting up dependency groups for development/testing, and ensuring `uv run pytest` works correctly.

⭐23stars🔀2forks📁View on GitHub🕐Updated Dec 30, 2025

When & Why to Use This Skill

This Claude skill automates the migration of legacy Python projects from setup.py and setup.cfg to the modern pyproject.toml format, specifically optimized for the uv package manager. It streamlines dependency management, configures standardized build-backends, and ensures seamless integration with modern Python development workflows, significantly reducing the manual effort required for project modernization.

Use Cases

  • Modernizing Legacy Codebases: Automatically convert aging setup.py or setup.cfg files into the standardized pyproject.toml format to comply with current PEP standards.
  • Adopting High-Performance Tooling: Transition Python projects to the uv package manager to benefit from faster dependency resolution, installation, and environment management.
  • Dependency Consolidation: Merge fragmented configuration files like requirements.txt and MANIFEST.in into a single, maintainable source of truth.
  • Optimizing Development Workflows: Configure specific dependency groups to ensure testing and linting tools like pytest and black work instantly with 'uv run' commands.
namesetup-to-pyproject
descriptionMigrate Python projects from setup.py/setup.cfg to pyproject.toml for use with uv. Use when upgrading legacy Python packaging, converting setup.py to modern pyproject.toml format, setting up dependency groups for development/testing, and ensuring `uv run pytest` works correctly.

Setup.py to pyproject.toml Migration for uv

Migrate legacy Python packaging to modern pyproject.toml with uv compatibility.

Core Structure

[project]
name = "package-name"
version = "0.1.0"
description = "Package description"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.28",
]
license = "Apache-2.0"

[project.urls]
Homepage = "https://github.com/user/repo"
Changelog = "https://github.com/user/repo/releases"
Issues = "https://github.com/user/repo/issues"
CI = "https://github.com/user/repo/actions"

[dependency-groups]
dev = [
    "pytest>=9.0",
    "black>=25.12.0",
]

[build-system]
requires = ["uv_build>=0.9.18,<0.10.0"]
build-backend = "uv_build"

Key Migration Steps

1. Extract metadata from setup.py

Map setup() arguments to [project] table:

  • name → name
  • version → version
  • description → description
  • long_description → readme (use filename)
  • author + author_email → authors = [{name = "...", email = "..."}]
  • url → project.urls.Homepage
  • python_requires → requires-python
  • install_requires → dependencies
  • entry_points.console_scripts → [project.scripts]

2. Set up dependency-groups for dev dependencies

Critical for uv run pytest to work:

[dependency-groups]
dev = [
    "pytest>=9.0",
    "black>=25.12.0",
]

3. Confirm it works with uv run

Then run tests with:

uv run pytest

The dev group will be picked up automatically by uv run.

4. Confirm it works with uv build

Test that building the package works correctly:

uv build

uv_build defaults to src/ layout. For flat layout (package directory at project root), add:

[tool.uv.build-backend]
module-root = ""

Files to Delete After Migration

  • setup.py
  • setup.cfg
  • MANIFEST.in (usually, unless complex includes)
  • requirements.txt / requirements-dev.txt (optional, uv manages these)