Install & Compatibility
Where this runs
tested against v84.0.0.20260812 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.544s · 19.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.442s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
setup
✓ from setuptools import setup
✗ from setuptools-stubs import setup
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.
import subprocess
import sys
# Create a dummy pyproject.toml for setuptools
with open('pyproject.toml', 'w') as f:
f.write('''
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
[project]
name = "my_package"
version = "0.1.0"
description = "A test package"
requires-python = ">=3.10"
[project.optional-dependencies]
dev = ["mypy", "types-setuptools"]
''')
# Create a dummy setup.py (optional, for demonstrating basic setup function)
with open('setup.py', 'w') as f:
f.write('''
from setuptools import setup, find_packages
setup(
name='my_package',
version='0.1.0',
packages=find_packages(where='src'),
package_dir={'': 'src'},
)
''')
# Create a simple module for type checking
import os
os.makedirs('src', exist_ok=True)
with open('src/my_module.py', 'w') as f:
f.write('''
from setuptools import setup # type: ignore
def build_package(name: str, version: str) -> None:
# In a real scenario, 'setup' would be called via build tools,
# but here we use it to show type checking potential.
# 'setup' itself is not typically called directly in modern builds.
print(f"Building {name}-{version}")
# Example of using setuptools types indirectly via a hypothetical build function
build_package("my_app", "1.0.0")
''')
# Try to run mypy (assuming it's installed in the environment)
print("\n--- Running MyPy without types-setuptools (if not in dev deps) ---")
try:
# This assumes mypy is available. If not, this part will fail but quickstart still illustrates intent.
subprocess.run([sys.executable, '-m', 'pip', 'install', 'mypy'], check=True, capture_output=True)
subprocess.run([sys.executable, '-m', 'mypy', '--ignore-missing-imports', 'src/my_module.py'], check=True, capture_output=True)
print("MyPy ran successfully (ignoring missing imports for setuptools).")
except subprocess.CalledProcessError as e:
print(f"MyPy failed: {e.stderr.decode()}")
except FileNotFoundError:
print("MyPy not found. Please install it with 'pip install mypy'.")
print("\n--- To fully leverage types-setuptools, ensure it's installed alongside setuptools and your type checker is configured. ---")
print("e.g. pip install setuptools types-setuptools mypy")
Debug
Known issues
breakingThe `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.fixEnsure 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.
affects: types-setuptools >= 71.1.x.y.z (corresponding to setuptools >= 71.1)
gotchaRecent `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.fixUpdate 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.
affects: setuptools >= 78.0.1 (and corresponding types-setuptools versions)
deprecatedThe `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.fixMigrate 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`.
affects: setuptools >= 49.0.0 (deprecation started), setuptools >= 72.0.0 (further removals)
Upgrade
Version history
84.0.0.20260812latest on PyPI · released Aug 12, 2026
Audit
Dependencies
pythonrequiredRequired for running the stubs.
setuptoolsrequiredThe stubs provide type information for this library; types-setuptools 82.0.0.20260210 targets setuptools==82.0.*.