GO — Healthy across the board

• Last commit 1d ago
• 23+ active contributors
• Distributed ownership (top contributor 27% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against OpenSSF Scorecard}

NumPy is the foundational Python library for numerical computing, providing a powerful N-dimensional array object (ndarray) and a comprehensive suite of functions for linear algebra, Fourier transforms, random number generation, and broadcasting operations. It bridges Python with optimized C, C++, and Fortran code to deliver high-performance scientific computing capabilities that underpin the entire Python data science ecosystem. Modular monorepo with clear separation: numpy/ contains the core pure-Python API and array implementation, numpy/_core/ houses low-level array mechanics and ufuncs, numpy/linalg/ wraps BLAS/LAPACK, numpy/fft/ provides Fourier operations, and numpy/random/ offers random number generators. Performance-critical paths are implemented in C/_src and exposed via Cython bindings (.pyx files). Build configuration lives in meson.build and pyproject.toml.

Data scientists, researchers, and scientific software engineers who need to perform vectorized numerical computations, manipulate multi-dimensional arrays, and integrate C/Fortran legacy code into Python workflows. Also used by downstream library maintainers (pandas, scikit-learn, SciPy) who build on NumPy's array infrastructure.

Highly mature and production-ready. NumPy has been actively developed for 20+ years with extensive CI/CD coverage (.github/workflows/ contains 20+ automated test pipelines for Linux, macOS, Windows, QEMU, and specialized hardware). The repo shows continuous active development with a large contributor base, comprehensive test infrastructure (pytest + hypothesis), and formal NumPy Enhancement Proposal (NEP) governance process. Breaking changes are carefully managed and documented.

Low risk for stable usage, but moderate complexity for contributors. The codebase is a massive mixed-language project (11.6M lines Python, 6.4M C, 793K C++, 152K Cython) requiring multiple build toolchains (Meson, BLAS/LAPACK, compilers). Key risks: (1) Meson build system adds complexity vs. legacy setuptools, (2) Platform-specific compilation issues across Linux/macOS/Windows/RISC-V can be hard to reproduce, (3) Performance regressions are critical given library's ubiquity. Single points of failure in core dtype/ufunc systems could impact millions of downstream users.

Active development across multiple fronts: migration to Meson build system (away from distutils), ongoing dtype/ufunc system modernization, NEP-driven feature proposals, and extensive CI/CD expansion (new pipelines for RISC-V, Emscripten, compiler sanitizers in .github/workflows/). Recent workflow additions suggest focus on platform coverage and security (codeql.yml, scorecards.yml, dependency-review.yml).

git clone https://github.com/numpy/numpy.git
cd numpy
python -m pip install -e . --no-build-isolation
python -c "import numpy; numpy.test()"

NumPy uses Meson + pip; ensure you have a C/Fortran compiler and BLAS/LAPACK development headers installed (libblas-dev, liblapack-dev on Ubuntu). Use .devcontainer/ for containerized setup.

Daily commands: Development workflow: after install, edit .py or .pyx files, then pip install -e . --no-build-isolation to rebuild. Run specific test: python -m pytest numpy/tests/test_array_function.py. Run full test suite: python -c "import numpy; numpy.test()". Faster iteration: edit tests in numpy/tests/, then pytest directly without reinstalling.

• numpy/__init__.py — Main entry point that exposes NumPy's public API and initializes core modules.
• numpy/_core — Core array and ufunc implementations that form the foundation of NumPy operations.
• numpy/meson.build — Build configuration file that defines compilation flags, dependencies, and extension modules.
• pyproject.toml — Project metadata, build system configuration, and dependency specifications for the entire package.
• .github/workflows/linux.yml — Primary CI/CD workflow that runs tests across supported platforms and validates code quality.
• CONTRIBUTING.rst — Developer guidelines covering contribution workflow, coding standards, and testing requirements.
• building_with_meson.md — Build system documentation explaining how to compile and develop NumPy locally.

• ndarray (Core Data Structure) (C struct with Python descriptor wrappers) — Represents multidimensional homogeneous array with metadata (shape, strides, dtype, flags).
  • Failure mode: Memory leaks if reference counting breaks; segfaults if strides are invalid.
• Universal Functions (ufuncs) (C callbacks with type signatures registered at module load) — Vectorized operations that apply element-wise functions across arrays with broadcasting.
  • Failure mode: Type mismatch exceptions; incorrect dtype promotion leads to silent truncation.
• dtype System (Type descriptor objects in C with Python caching) — Type registry and coercion rules that define scalar and structured array types.
  • Failure mode: Misaligned struct packing; endianness confusion on mixed-architecture systems.
• BLAS/LAPACK Integration Layer (Fortran calling conventions wrapped in C; dynamic linking at runtime) — Routes linear algebra operations to system BLAS/LAPACK or vendor implementations.
  • Failure mode: Linker errors if BLAS not installed; numerical instability if using unoptimized fallback.
• Memory Allocator & Cache (CPython PyMem API; custom cache pool) — Allocates and pools memory for array data using malloc/mmap with optional reuse.
  • Failure mode: Out-of-memory exceptions; memory fragmentation on large-scale computations.
• Indexing Engine (C iteration with NumPy's index_helper C API) — Resolves fancy indexing (arrays of indices, boolean masks) to strides and offsets.
  • Failure mode: Out-of-bounds access if bounds checking disabled; inconsistent results with negative strides.

• Python User Code → NumPy Public API (numpy/__init__.py) — User imports and calls functions like np.array(), np.dot(), or operations on ndarray objects.
• NumPy Public API → Core Array Engine (_core module) — API dispatches to compiled C/C++ kernels, ufunc machinery, and dtype/shape validation logic.
• Core Array Engine → BLAS/LAPACK Libraries — Linear algebra operations (dot, solve, eig) delegate to external optimized libraries if available.
• Core Array Engine → Memory Allocator — Array creation and in-place operations request memory blocks and manage lifecycle.
• ndarray Result → Python User Code — Computed array is returned as an ndarray object with metadata (dtype, shape, strides).

Add a New Universal Function (ufunc)

1. Define the ufunc in the appropriate C source file within numpy/_core/src (numpy/_core/src)
2. Register the ufunc in the corresponding meson.build for compilation (numpy/_core/meson.build)
3. Expose the ufunc in numpy/_core/init.py to the public API (numpy/_core/__init__.py)
4. Add tests in the appropriate test file under numpy/_core/tests/ (numpy/_core/tests)

Add a New NumPy Submodule

1. Create a new directory under numpy/ with init.py (numpy/__init__.py)
2. Define meson.build in the new submodule directory (meson.build)
3. Import and expose the submodule in numpy/init.py (numpy/__init__.py)
4. Create tests/ subdirectory with test files following numpy naming conventions (numpy/tests)

Modify Build Configuration

1. Edit the relevant meson.build file in the module hierarchy (meson.build)
2. Update pyproject.toml if changing build dependencies or backend settings (pyproject.toml)
3. Test locally using: pip install -e . --no-build-isolation (building_with_meson.md)
4. Verify CI passes by checking .github/workflows/linux.yml locally or in PR (.github/workflows/linux.yml)

• Meson Build System — Provides fast, reliable cross-platform compilation with excellent C/C++ extension support and NumPy's complex dependency management.
• C/C++ Core with Python Bindings — Achieves performance-critical array operations in compiled code while maintaining accessibility through Python API.
• BLAS/LAPACK Integration — Leverages optimized linear algebra libraries from system packages or vendor implementations (MKL, OpenBLAS, Accelerate).
• GitHub Actions Workflows — Provides comprehensive multi-platform CI/CD testing across Linux, Windows, macOS, and specialized architectures (RISC-V, IBM Power, Emscripten).

• C core with Python API instead of pure Python

  • Why: NumPy must support scientific computing at scale with minimal performance overhead.
  • Consequence: Increases build complexity and platform-specific compilation challenges, but enables array operations 100–1000× faster than pure Python.

• Meson over setup.py/setuptools

  • Why: Meson provides superior C extension support, dependency resolution, and build parallelization.
  • Consequence: Requires contributors to learn Meson; older tools (setup.py) are still referenced in legacy code paths.

• Optional BLAS/LAPACK backends

  • Why: Allows users to plug in optimized implementations (MKL, OpenBLAS, Accelerate) for their hardware.
  • Consequence: Adds complexity to build configuration and potential runtime linking issues if backend is misconfigured.

• Does not implement GPU acceleration; GPU offloading is handled by third-party libraries (CuPy, Jax).
• Does not provide real-time or streaming data structures; designed for in-memory batch computations.
• Does not include distributed array operations; users must layer Dask or other frameworks on top.
• Does not guarantee thread safety on individual array operations; GIL is released selectively.
• Does not target resource-constrained environments; minimum dependencies include BLAS/LAPACK systems libraries.

• Avg cyclomatic complexity: ~6.8 — NumPy combines high-level Python ergonomics with low-level C kernels; dtype promotion, broadcasting, and memory layout introduce cyclomatic complexity in both layers. Ufunc machinery and indexing engines are particularly intricate.
• Largest file: numpy/_core/src/multiarray/ (15,000 lines)
• Estimated quality issues: ~47 — Mix of legacy C89 code and modern C11 extensions; incomplete type hints in Python API; some undocumented C struct fields. Meson migration ongoing, leaving some build inconsistencies. Extensive use of global registry patterns.

• Global State in C Extensions (Medium) — numpy/_core/src: Some ufunc registries and type caches use static C variables, risking thread-safety issues if not properly guarded.
• Implicit dtype Coercion (Medium) — numpy/_core: Broadcasting rules implicitly promote dtypes (int + float → float), which can silently lose precision or cause unexpected casts.
• Memory View Aliasing (Low) — numpy/_core: Array slicing and views create aliases to the same underlying buffer; in-place modifications affect all views unexpectedly.

• BLAS/LAPACK Dispatch (External Dependency & I/O) — Linear algebra operations serialize to external library calls, creating a bottleneck if BLAS is unoptimized or unavailable.
• dtype Promotion & Type Resolution (Computational Overhead) — NumPy's complex dtype promotion rules involve table lookups and C struct inspection for every binary operation.
• Memory Allocation & GC (Memory Management) — Large array allocations trigger system malloc which can be slow; Python's GC may pause when collecting large ndarray objects.
• Advanced Indexing (Fancy Indexing) (Algorithmic Complexity) — Boolean masks and integer arrays require iteration and temporary copies, slower than simple slicing.

(1) Meson build requires running pip install -e . --no-build-isolation with a C/Fortran compiler in PATH; plain pip install from Git fails. (2) Cython .pyx files require recompilation; edits don't auto-reload in Python REPL—must reinstall. (3) Dtype/ufunc changes have subtle broadcasting implications; always run full test suite, not subset. (4) Performance regressions are caught by CI but local machines may vary (different BLAS libraries, CPU architecture)—use Linux CI for confidence. (5) .devcontainer/setup.sh exists; use it if local build fails.

• Broadcasting — NumPy's broadcasting rules allow operations on arrays of different shapes to be automatically aligned—fundamental to avoiding explicit loops and is a unique strength of NumPy design you'll see throughout the codebase (numpy/_core/shape_base.py, many ufunc implementations)
• Universal Functions (ufuncs) — Ufuncs are NumPy's mechanism for element-wise operations that support broadcasting and multiple input/output arrays—implemented in numpy/_core/umath.pyx and numpy/_core/ufunc_object.c, they're the high-performance backbone of NumPy
• Memory Layout & Strides — NumPy arrays can be C-contiguous or Fortran-ordered, with stride-based indexing avoiding copies—critical for performance optimization and non-contiguous view creation (see numpy/lib/stride_tricks.py)
• Dtype System — NumPy's flexible dtype system (int32, float64, complex128, structured dtypes, etc.) with automatic promotion rules is fundamental to array behavior—implemented in numpy/_core/dtype.py and numpy/_core/dtypes.py, changes here affect all operations
• C API & ctypes / Cython Bindings — NumPy exposes a C API for external libraries to create/manipulate arrays without Python overhead—implemented in numpy/_core/include/ and wrapped via Cython .pyx files; essential for integrating Fortran/C code
• NEP (NumPy Enhancement Proposal) Process — Major changes to NumPy require community discussion via NEPs (similar to Python PEPs); documents in doc/neps/ show governance and design decisions you need to understand before proposing large changes
• F2PY (Fortran-to-Python) — NumPy's Fortran wrapping tool that auto-generates Python bindings from Fortran code—used extensively for LAPACK/BLAS wrapping and explains why .f files exist in numpy/linalg/_src/

• scipy/scipy — Builds on NumPy to provide higher-level scientific algorithms (optimization, statistics, signal processing); tight integration via shared array protocols
• pandas-dev/pandas — Uses NumPy ndarrays as underlying data structure for Series/DataFrames; close coupling means NumPy releases often trigger pandas compatibility work
• scikit-learn/scikit-learn — Primary user of NumPy for machine learning; performance improvements and breaking changes in NumPy directly affect ML code
• numpy/numpy-stubs — Separate repo housing advanced type stubs for NumPy (pre-2.0 era); being integrated back into main numpy/ for unified typing
• pydata/array-api — Standardization effort to make NumPy, PyTorch, and other array libraries API-compatible; NumPy is implementing array-api standard

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive type stubs for numpy.core submodules

The repo has .github/workflows/stubtest.yml and typecheck.yml indicating active type checking efforts, but many internal numpy.core submodules likely lack complete .pyi stub files. This is high-value because it improves IDE support, type safety for downstream users, and catches bugs early. The existing workflow infrastructure shows this is a priority.

• [ ] Identify which numpy.core submodules are missing or have incomplete .pyi files (check against numpy/core directory structure)
• [ ] Generate or manually create stub files for key submodules like numpy.core.multiarray, numpy.core.umath, numpy.core._methods
• [ ] Run existing stubtest.yml workflow locally to validate stubs against actual implementations
• [ ] Add new stubs to the type checking pipeline and ensure typecheck.yml passes

Add platform-specific SIMD optimization tests in CI

The repo has .github/workflows/linux_simd.yml but it's unclear if all SIMD code paths are adequately tested across different CPU architectures. Given the file list shows multiple architecture-specific workflows (linux_qemu.yml, linux_riscv64.yml, linux-ibm.yml), there's an opportunity to add dedicated unit tests that validate SIMD optimizations work correctly and don't regress.

• [ ] Audit numpy/core/src/_ufunc_config.h and SIMD-related files in numpy/_core/_simd/ for untested code paths
• [ ] Create new test file numpy/_core/tests/test_simd_kernels.py with tests for AVX2, AVX512, NEON, and SSE optimizations
• [ ] Integrate these tests into the existing linux_simd.yml workflow to run on each SIMD target
• [ ] Add documentation in CONTRIBUTING.rst about how to test SIMD changes locally

Add missing type annotations for numpy.ma (masked array) module

The numpy.ma module is a mature, widely-used submodule for masked arrays, but based on type-checking workflows being present and no apparent stubs in the file list, it likely lacks comprehensive type hints. This improves usability for type-aware users and reduces support burden. The existing mypy_primer.yml workflow shows type quality is monitored.

• [ ] Scan numpy/ma/ directory to identify functions/classes with missing type annotations
• [ ] Add type hints to key classes like MaskedArray and public functions in numpy/ma/init.py
• [ ] Create stub file numpy/ma/init.pyi for complex masked array operations
• [ ] Run mypy_primer.yml workflow to validate changes don't break type checking for downstream projects

• Add type annotations to numpy/lib/utils.py (currently has incomplete stubs)—improves IDE support and typechecker compliance without changing runtime behavior.
• Expand error messages in numpy/_core/dtypes.py when dtype mismatches occur (e.g., suggest compatible dtypes in ValueError)—low-risk UX improvement with high user impact.
• Write integration tests in numpy/tests/test_numpy_api.py for public API coverage of lesser-used array functions (e.g., numpy.lib.stride_tricks)—improves regression detection.

NumPy repository demonstrates reasonable security practices with organized CI/CD pipelines, proper use of GitHub security features (.github directory structure), and documentation standards. However, security could be improved by: (1) implementing explicit dependency locking, (2) auditing CI/CD workflows for secret exposure and injection risks, (3) documenting security audit practices for submodules, and (4) ensuring setup scripts are free of sensitive information. No critical vulnerabilities were identified based on the file structure analysis, but a deeper review of workflow files, dependency manifests, and actual code content would be needed for comprehensive assessment.

• Low · Potential dependency management risk — Repository root / Package management configuration. No dependency lock file (requirements-lock.txt, Pipfile.lock, poetry.lock) is visible in the provided file structure. This could lead to non-reproducible builds and potential installation of compromised dependency versions. Fix: Implement and maintain a lock file for all dependencies. Use tools like pip-tools, Poetry, or Pipenv to lock dependency versions and ensure reproducible builds.
• Low · DevContainer configuration exposure — .devcontainer/setup.sh. The .devcontainer/setup.sh file is present and tracked in version control. While not necessarily a vulnerability, setup scripts can accidentally contain sensitive information or insecure practices. Fix: Review the setup.sh script to ensure it doesn't contain hardcoded credentials, secrets, or insecure configurations. Use environment variables for sensitive data.
• Low · Submodule configuration present — .gitmodules. The .gitmodules file indicates use of Git submodules. If submodules point to external repositories, there's a risk of supply chain attacks if those repositories are compromised. Fix: Regularly audit submodule sources, pin submodules to specific commits (not branches), and monitor for updates. Consider vendoring critical dependencies instead.
• Low · CI/CD pipeline complexity — .github/workflows/. Multiple GitHub Actions workflows are present (.github/workflows/). Complex CI/CD pipelines can introduce security issues if not properly secured, including exposure of secrets or execution of untrusted code. Fix: Audit all workflow files for: proper secret management, least-privilege permissions, use of pinned action versions, and protection against injection attacks. Implement CODEOWNERS review requirements for workflow changes.
• Low · Clang-format configuration present — .clang-format. .clang-format configuration file is present. While not a direct vulnerability, custom formatting rules can sometimes hide or introduce code quality issues. Fix: Ensure clang-format configuration is regularly reviewed and uses security-aware lint rules. Consider integrating additional static analysis tools.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/numpy/numpy shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live numpy/numpy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/numpy/numpy.

What it runs against: a local clone of numpy/numpy — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in numpy/numpy | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of numpy/numpy. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/numpy/numpy.git
#   cd numpy
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of numpy/numpy and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "numpy/numpy(\\.git)?\\b" \\
  && ok "origin remote is numpy/numpy" \\
  || miss "origin remote is not numpy/numpy (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "numpy/__init__.py" \\
  && ok "numpy/__init__.py" \\
  || miss "missing critical file: numpy/__init__.py"
test -f "numpy/_core" \\
  && ok "numpy/_core" \\
  || miss "missing critical file: numpy/_core"
test -f "numpy/meson.build" \\
  && ok "numpy/meson.build" \\
  || miss "missing critical file: numpy/meson.build"
test -f "pyproject.toml" \\
  && ok "pyproject.toml" \\
  || miss "missing critical file: pyproject.toml"
test -f ".github/workflows/linux.yml" \\
  && ok ".github/workflows/linux.yml" \\
  || miss "missing critical file: .github/workflows/linux.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/numpy/numpy"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.