{"id":963,"library":"types-setuptools","title":"Typing Stubs for setuptools","description":"types-setuptools is a type stub package that provides accurate type annotations for the setuptools library. It enables type checkers like MyPy and Pyright to analyze code using setuptools, ensuring type safety and catching potential errors during development. This package is part of the broader typeshed project, which centralizes high-quality type stubs for many popular Python libraries. The current version aims to provide annotations for setuptools==82.0.* and is frequently updated to reflect changes in setuptools.","status":"active","version":"82.0.0.20260210","language":"python","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","setuptools","typeshed","mypy","pyright"],"install":[{"cmd":"pip install types-setuptools","lang":"bash","label":"Install types-setuptools"},{"cmd":"pip install 'setuptools<71.1' types-setuptools # For older setuptools versions needing pkg_resources types","lang":"bash","label":"Install with older setuptools (if pkg_resources types are needed)"}],"dependencies":[{"reason":"Required for running the stubs.","package":"python","version":">=3.10"},{"reason":"The stubs provide type information for this library; types-setuptools 82.0.0.20260210 targets setuptools==82.0.*.","package":"setuptools","version":"==82.0.*","optional":false}],"imports":[{"note":"types-setuptools provides type hints for this and other setuptools symbols.","symbol":"setup","correct":"from setuptools import setup"},{"note":"types-setuptools provides type hints for this and other setuptools symbols.","symbol":"find_packages","correct":"from setuptools import find_packages"}],"quickstart":{"code":"import subprocess\nimport sys\n\n# Create a dummy pyproject.toml for setuptools\nwith open('pyproject.toml', 'w') as f:\n    f.write('''\n[build-system]\nrequires = [\"setuptools>=61.0\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"my_package\"\nversion = \"0.1.0\"\ndescription = \"A test package\"\nrequires-python = \">=3.10\"\n\n[project.optional-dependencies]\ndev = [\"mypy\", \"types-setuptools\"]\n''')\n\n# Create a dummy setup.py (optional, for demonstrating basic setup function)\nwith open('setup.py', 'w') as f:\n    f.write('''\nfrom setuptools import setup, find_packages\n\nsetup(\n    name='my_package',\n    version='0.1.0',\n    packages=find_packages(where='src'),\n    package_dir={'': 'src'},\n)\n''')\n\n# Create a simple module for type checking\nimport os\nos.makedirs('src', exist_ok=True)\nwith open('src/my_module.py', 'w') as f:\n    f.write('''\nfrom setuptools import setup # type: ignore\n\ndef build_package(name: str, version: str) -> None:\n    # In a real scenario, 'setup' would be called via build tools, \n    # but here we use it to show type checking potential. \n    # 'setup' itself is not typically called directly in modern builds.\n    print(f\"Building {name}-{version}\")\n\n# Example of using setuptools types indirectly via a hypothetical build function\nbuild_package(\"my_app\", \"1.0.0\")\n''')\n\n# Try to run mypy (assuming it's installed in the environment)\nprint(\"\\n--- Running MyPy without types-setuptools (if not in dev deps) ---\")\ntry:\n    # This assumes mypy is available. If not, this part will fail but quickstart still illustrates intent.\n    subprocess.run([sys.executable, '-m', 'pip', 'install', 'mypy'], check=True, capture_output=True)\n    subprocess.run([sys.executable, '-m', 'mypy', '--ignore-missing-imports', 'src/my_module.py'], check=True, capture_output=True)\n    print(\"MyPy ran successfully (ignoring missing imports for setuptools).\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"MyPy failed: {e.stderr.decode()}\")\nexcept FileNotFoundError:\n    print(\"MyPy not found. Please install it with 'pip install mypy'.\")\n\nprint(\"\\n--- To fully leverage types-setuptools, ensure it's installed alongside setuptools and your type checker is configured. ---\")\nprint(\"e.g. pip install setuptools types-setuptools mypy\")\n","lang":"python","description":"To leverage `types-setuptools`, simply install it in your project's environment alongside `setuptools` and your chosen type checker (e.g., MyPy, Pyright). The type checker will automatically discover and apply the provided stubs to your code that uses `setuptools` APIs, allowing for static analysis and early detection of type-related issues in your packaging configuration or custom build scripts. The example demonstrates a minimal `pyproject.toml` and a Python module using `setuptools` imports, highlighting how a type checker benefits from the stubs. Note that `setup()` is rarely called directly in modern `setuptools` workflows."},"warnings":[{"fix":"Ensure you are using `setuptools >= 71.1` to get inline types for `pkg_resources`. If you must use an older `setuptools` version, you may need to provide your own stubs for `pkg_resources` or disable type checking for that module.","message":"The `pkg_resources` module's type stubs are no longer included in `types-setuptools` for `setuptools` versions 71.1 and newer. This is because `setuptools` itself now ships with inline type annotations for `pkg_resources`. If you are using an older version of `setuptools` (<71.1) and require types for `pkg_resources`, `types-setuptools` will not provide them.","severity":"breaking","affected_versions":"types-setuptools >= 71.1.x.y.z (corresponding to setuptools >= 71.1)"},{"fix":"Update your `setup.cfg` files to use underscore-separated keys as required by modern `setuptools`. Refer to the `setuptools` documentation for the correct syntax. Pinning `setuptools` to an older version (e.g., `setuptools<78`) is a temporary workaround.","message":"Recent `setuptools` versions (e.g., 78.0.1 and later) introduced strict enforcement of naming conventions in `setup.cfg` files, disallowing dash-separated keys (e.g., `description-file`) in favor of underscore-separated ones (e.g., `description_file`). While this is a change in `setuptools` itself, `types-setuptools` reflects the current API. Using outdated `setup.cfg` syntax with newer `setuptools` and `types-setuptools` can lead to type checker errors or build failures.","severity":"gotcha","affected_versions":"setuptools >= 78.0.1 (and corresponding types-setuptools versions)"},{"fix":"Migrate your project to use a `pyproject.toml` file with PEP 517/621 compatible build backends and frontends (e.g., `pip` with `setuptools.build_meta`). Avoid direct execution of `setup.py`.","message":"The `setup.py develop` command and other direct `setup.py` invocations are deprecated in `setuptools` and will be removed. While `types-setuptools` provides stubs for these legacy APIs for compatibility, relying on them is discouraged. Type checkers may flag usage of these deprecated features based on the provided stubs.","severity":"deprecated","affected_versions":"setuptools >= 49.0.0 (deprecation started), setuptools >= 72.0.0 (further removals)"}],"env_vars":null,"last_verified":"2026-05-12T21:46:12.491Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"pip install types-setuptools","cause":"MyPy cannot find type annotations for the `setuptools` library, indicating that the `types-setuptools` stub package is not installed or not recognized by your type checker.","error":"error: Missing type stubs for \"setuptools\" (or corresponding \"types-setuptools\" package)"},{"fix":"pip install types-setuptools","cause":"Pyright reports that it cannot find type information for the `setuptools` library, usually because the `types-setuptools` stub package has not been installed.","error":"Module 'setuptools' has no type hints available. Consider installing 'types-setuptools'. (reportMissingTypeStubs)"},{"fix":"Change your import statement from `from types_setuptools import ...` to `from setuptools import ...`.","cause":"You are attempting to import directly from the `types-setuptools` stub package, which only provides type annotations for `setuptools` and is not meant for runtime imports.","error":"ModuleNotFoundError: No module named 'types_setuptools'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"82.0.0.20260508","cli_name":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.84,"mem_mb":15.7,"disk_size":"19.4M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.81,"mem_mb":15.7,"disk_size":"19.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.55,"mem_mb":15.7,"disk_size":"20M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.53,"mem_mb":15.7,"disk_size":"20M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.96,"mem_mb":17.2,"disk_size":"21.6M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.07,"mem_mb":17.2,"disk_size":"21.6M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.89,"mem_mb":17.2,"disk_size":"22M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.79,"mem_mb":17.2,"disk_size":"22M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"12.1M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":null,"mem_mb":null,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"11.8M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":null,"mem_mb":null,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.82,"mem_mb":15.3,"disk_size":"18.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.85,"mem_mb":15.3,"disk_size":"18.9M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.65,"mem_mb":15.4,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.68,"mem_mb":15.4,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}