Skip to main content

How to Resolve "RuntimeError: Package Fails to Pass a Sanity Check" for NumPy and Pandas in Python

The "RuntimeError: Package Fails to Pass a Sanity Check" error is a well-known issue that primarily affects Windows users working with specific versions of NumPy and Pandas. It was most commonly triggered when using Python 3.9 with NumPy 1.19.4, due to a bug related to the Windows runtime. However, it can also surface in other version combinations or when Pandas depends on an incompatible NumPy build.

In this guide, you'll learn what causes this error, how to identify the exact problem, and multiple ways to fix it for both NumPy and Pandas.

Understanding the Error​

When you try to import NumPy or Pandas and see this error, it means the installed package failed an internal validation step that checks whether the library can function correctly on your operating system.

Triggering the error with NumPy:

import numpy

Error output:

RuntimeError: The current Numpy installation
('C:\Users\YourUser\...\numpy\__init__.py') fails to pass a sanity check
due to a bug in the windows runtime. See this issue for more information:
https://tinyurl.com/y3dm3h86

Triggering the error with Pandas:

import pandas

Error output:

RuntimeError: The current Numpy installation
('C:\Users\YourUser\...\numpy\__init__.py') fails to pass a sanity check
due to a bug in the windows runtime.
info

Even though the error appears when importing Pandas, the root cause is still NumPy. Pandas depends on NumPy internally, so a broken NumPy installation will cascade and break Pandas as well.

Why Does This Error Occur?​

This error is caused by a specific combination of factors:

  1. A Windows runtime bug: NumPy 1.19.4 introduced a sanity check that deliberately raises this error on Windows when it detects a known bug in the Windows runtime (ucrtbase.dll). This bug could silently produce incorrect math results, so the NumPy developers chose to fail loudly instead.
  2. Python 3.9 + NumPy 1.19.4 incompatibility: Python 3.9 was relatively new when NumPy 1.19.4 was released, and the combination on Windows triggered the problematic code path.
  3. Outdated NumPy pulled as a dependency: Installing an older version of Pandas (or another scientific package) can pull in an incompatible version of NumPy, triggering the error even on newer Python versions.
  4. Conda environment conflicts: Mixed pip and conda installs can result in incompatible package versions coexisting in the same environment.

How to Fix the Error​

The simplest and most reliable fix is to upgrade NumPy to a version that has resolved the sanity check issue. Versions 1.19.5 and above include the fix.

pip install --upgrade numpy

After upgrading, verify the installed version and test the import:

import numpy as np
print(np.__version__)

Expected output:

2.1.3

If Pandas was also affected, it should now import correctly without any changes:

import pandas as pd
print(pd.__version__)

Expected output:

2.2.3
tip

If you need both NumPy and Pandas, upgrade them together to ensure version compatibility:

pip install --upgrade numpy pandas

Fix 2: Install a Specific Compatible NumPy Version​

If upgrading to the latest version isn't an option (e.g., due to project constraints), install a specific version that includes the fix but remains close to your current version:

pip install numpy==1.19.5

Or skip the problematic version entirely:

pip install "numpy>=1.20,<2.0"

Fix 3: Use psycopg2-binary-Style Approach: Install the Pre-built Binary​

In some cases, the issue stems from how NumPy was compiled. Force a reinstall using only pre-built binary wheels (no source compilation):

pip install --only-binary :all: numpy

This ensures you get a wheel that was built and tested for your specific platform and Python version.

Fix 4: Downgrade Python (Last Resort)​

If you're locked into a specific NumPy version that doesn't support Python 3.9+, you may need to use an earlier Python version. This is rarely necessary today but was a common workaround in late 2020.

# Using pyenv (Linux/macOS)
pyenv install 3.8.18
pyenv local 3.8.18

# Using conda
conda create -n myenv python=3.8
conda activate myenv
pip install numpy==1.19.4
warning

Downgrading Python should be a last resort. In almost all cases, upgrading NumPy is the better solution.

Fix 5: Set a Windows Environment Variable (Temporary Workaround)​

There is an undocumented environment variable that disables the sanity check on Windows. This suppresses the error but does not fix the underlying Windows runtime bug, meaning you could get silently incorrect math results.

Command Prompt:

set NPY_DISABLE_CPU_FEATURES=1
python -c "import numpy; print(numpy.__version__)"

PowerShell:

$env:NPY_DISABLE_CPU_FEATURES="1"
python -c "import numpy; print(numpy.__version__)"
danger

This workaround silences the error without fixing the root cause. NumPy may produce incorrect numerical results on affected systems. Only use this for debugging purposes, never in production.

Fix 6: Use a Clean Virtual Environment​

Conflicting packages in your environment can cause unexpected version mismatches. Creating a fresh virtual environment often resolves the issue:

python -m venv fresh_env
# On Windows:
fresh_env\Scripts\activate
# On Linux/macOS:
source fresh_env/bin/activate

pip install numpy pandas

Verify everything works:

import numpy as np
import pandas as pd

print(f"NumPy version:  {np.__version__}")
print(f"Pandas version: {pd.__version__}")

# Quick sanity check
arr = np.array([1, 2, 3, 4, 5])
df = pd.DataFrame({"values": arr})
print(f"\nSum via NumPy:  {np.sum(arr)}")
print(f"Sum via Pandas: {df['values'].sum()}")

Expected output:

NumPy version:  2.1.3
Pandas version: 2.2.3

Sum via NumPy:  15
Sum via Pandas: 15

Fix 7: Use Conda Instead of pip​

If you're using Anaconda or Miniconda, let conda handle the dependency resolution. Conda is generally better at resolving binary compatibility on Windows:

conda install numpy pandas

Or create a new environment with specific versions:

conda create -n myproject python=3.11 numpy pandas
conda activate myproject

Common Mistake: Mixing pip and conda​

A frequent cause of version conflicts (and this error) is installing some packages with pip and others with conda in the same environment.

Wrong approach:

conda install pandas
pip install numpy==1.19.4    # May conflict with conda's version

Correct approach: pick one package manager and stick with it:

# Option A: Use conda for everything
conda install numpy pandas

# Option B: Use pip for everything (in a venv)
python -m venv myenv
source myenv/bin/activate
pip install numpy pandas

Quick Reference: Solutions Summary​

SolutionCommandWhen to Use
Upgrade NumPypip install --upgrade numpyBest default fix
Upgrade NumPy + Pandaspip install --upgrade numpy pandasWhen both packages are involved
Pin a safe versionpip install numpy==1.19.5Need to stay near 1.19.x
Force binary installpip install --only-binary :all: numpyCompilation issues
Clean virtual environmentpython -m venv fresh_envEnvironment conflicts
Use condaconda install numpy pandasConda-based workflows

Conclusion​

The "RuntimeError: Package Fails to Pass a Sanity Check" error for NumPy and Pandas is almost always caused by an outdated NumPy version (specifically 1.19.4) running on Windows with Python 3.9. The NumPy developers intentionally added this check to prevent a Windows runtime bug from producing silently incorrect calculations.

The fastest and most reliable fix is simply upgrading NumPy:

pip install --upgrade numpy

For Pandas users, remember that Pandas depends on NumPy internally: fixing NumPy automatically fixes Pandas. When in doubt, start with a clean virtual environment, install the latest versions of both packages, and let the dependency resolver handle compatibility for you.

Table of Contents