Do You Still Need pandas-stubs? What pandas 100% Type-Complete Means for Your Projects

Mar 11, 2026

I ran pip install pandas-stubs the other day and paused. Do I still need this?

My pyproject.toml had both pandas and pandas-stubs in the dev dependencies. I’d been doing this for years—copy-pasting the same setup across projects without questioning it. Then I remembered seeing something about pandas improving its type coverage.

Let me check what’s actually needed now.

The Confusion

I found a Reddit thread about pandas reaching 100% type-complete. The top comment (52 upvotes) asked:

“So should we still be installing pandas-stubs alongside pandas?”

That this was the most upvoted question told me I wasn’t alone. Many Python developers are confused about the relationship between pandas and pandas-stubs.

Here’s what was happening:

┌─────────────────────────────────────────────────────────┐
│  Your Project                                           │
│                                                         │
│   ┌─────────┐    ┌──────────────┐                      │
│   │ pandas  │    │ pandas-stubs │  ← Two packages     │
│   │  2.0.0  │    │    2.0.0     │    for one library   │
│   └────┬────┘    └──────┬───────┘                      │
│        │                │                              │
│        ▼                ▼                              │
│   Runtime code      Type hints only                   │
│   (actual use)      (for mypy/pyright)                │
│                                                         │
│   Problem: 47% of pandas had no type hints            │
│   Solution: Community maintained pandas-stubs          │
└─────────────────────────────────────────────────────────┘

Historically, pandas had incomplete type annotations—only about 47% coverage. The pandas-stubs package was created to fill the gap. Every tutorial, every Stack Overflow answer recommended installing both.

This created problems:

Version drift: Your pandas version might not match pandas-stubs
Maintenance burden: One more package to update
Conflicting types: Sometimes the stubs disagreed with reality

What Changed

pandas improved from 47% to 100% type-complete. The inline type hints are now bundled directly in the main pandas package.

┌─────────────────────────────────────────────────────────┐
│  Your Project                                           │
│                                                         │
│   ┌─────────────────────┐                              │
│   │      pandas         │                              │
│   │       2.1+          │  ← One package              │
│   └──────────┬──────────┘                              │
│              │                                         │
│              ▼                                         │
│   ┌─────────────────────┐                              │
│   │ Runtime + Type Hints│                              │
│   │   (100% coverage)   │                              │
│   └─────────────────────┘                              │
│                                                         │
└─────────────────────────────────────────────────────────┘

No more separate stub package needed for the public API.

What I Did

Step 1: Check my current pandas version.

pip show pandas | grep Version
# Version: 2.1.4

If you’re below 2.1, upgrade first.

Step 2: Remove pandas-stubs.

pip uninstall pandas-stubs

Step 3: Update pyproject.toml.

Before:

[project]
dependencies = [
    "pandas>=2.0.0",
    "pandas-stubs>=2.0.0",  # No longer needed!
]

[project.optional-dependencies]
dev = [
    "mypy>=1.0.0",
    "pandas-stubs>=2.0.0",  # No longer needed!
]

After:

[project]
dependencies = [
    "pandas>=2.1.0",  # Type hints included!
]

[project.optional-dependencies]
dev = [
    "mypy>=1.0.0",
]

Step 4: Verify type checking still works.

mypy your_project/
# Should see no errors related to missing pandas stubs

Or with Pyright:

pyright your_project/
# Should correctly infer pandas types

Mistakes I Almost Made

Mistake 1: Keeping pandas-stubs “just in case”

I almost left it in requirements because I worried about edge cases. But if pandas has inline hints, the stubs will only conflict. Remove it.

Mistake 2: Not updating CI/CD

I removed it from my local pyproject.toml but forgot about GitHub Actions. The build passed locally, failed in CI. Check all your requirements files.

Mistake 3: Confusing runtime and static type checking

pandas having type hints doesn’t mean runtime type validation. This is still just static analysis. If you need runtime checking, you still need something like pydantic or typeguard.

Why This Matters

Simpler dependencies: One less thing to think about.

No version mismatch: Type hints always match the pandas version you’re running.

Better IDE experience: Inline hints give more accurate autocomplete than stub files because they’re in the actual source code.

Smaller attack surface: Fewer dependencies means fewer potential supply chain vulnerabilities.

When You Might Still Need pandas-stubs

There are edge cases:

Internal/private APIs: If you use pandas internal functions that aren’t part of the public API, those might not be typed.
Old pandas versions: If you’re pinned to pandas < 2.1 for compatibility, you still need the stubs.
Third-party type checkers with specific requirements: Some tools might still look for separate stub files, though this is rare.

For most projects using the standard pandas public API with pandas 2.1+, you’re done.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 pandas' Public API Is Now Type-Complete - Reddit Discussion
👨‍💻 pandas What's New - Official Documentation
👨‍💻 pandas GitHub Repository

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!