Skip to main content

image image image image

unref

Find dead code in Python projects: the unused functions, classes, methods, variables and attributes that nothing references.

Documentation: unref.readthedocs.io

Why

Unused code piles up in every codebase, faster than ever now that AI tools write much of it.

Ruff does not find unused code yet, see astral-sh/ruff#872. unref fills that gap until it does:

  • Just works: built-in rules for pytest, unittest, Pydantic, SQLAlchemy and FastAPI, so most projects need little or no configuration.
  • Ruff-style: same conventions, options and output style, and it covers what Ruff leaves out.
  • Fast: checks all of CPython in seconds.
  • Modern: ty-style rule codes and configuration in pyproject.toml.

Quick start

Run it with uvx:

$ uvx unref
src/project/models.py:12:7: unused-class 'Account'
src/project/utils.py:40:5: unused-function 'parse_date'

Or as a pre-commit or prek hook, alongside Ruff:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.17.4
    hooks:
      - id: ruff-check
      - id: ruff-format
  - repo: https://github.com/Apakottur/unref
    rev: v0.1.0 # Or run `pre-commit autoupdate`.
    hooks:
      - id: unref

How it works

  • Matched by module: a function, class or variable is used only when its own module reads it, or another module reaches it through an import, module.name or __all__.
  • Installed base classes: base classes from the project's environment are followed, so the methods a subclass overrides count as used.
  • Ignore comments by code: # unref: ignore[...] names the rule it ignores, and a comment that ignores nothing is reported.

Benchmark

Checking the whole CPython codebase (v3.14.0, about 2,100 files):

Tool Time
unref 3.96s
unref (one process) 9.32s
vulture 14.87s

Measured with scripts/benchmark.py.

Contributing

False positives and other bugs are welcome as issues. To contribute code, see CONTRIBUTING.md.

Metadata

Release files for unref 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for unref 0.1.1
File Size Uploaded Provenance Actions
unref-0.1.1.tar.gz 184.2 kB Without provenance Details for unref-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for unref 0.1.1
File Interpreter ABI Platform Actions
unref-0.1.1-py3-none-any.whl Python 3 none any Details for unref-0.1.1-py3-none-any.whl

Total release size: 234.7 kB

Release files / unref-0.1.1.tar.gz

Download URL unref-0.1.1.tar.gz
Size 184.2 kB
Tags Source
SHA-256 checksum
How to use checksums
c89242ca25510466f7d6e8c0d2fe996764d4e15b4aed28b0361a3e7850bd0439
BLAKE2b-256 checksum
How to use checksums
834feb757324914b8eacce1e0fcf9ccb80add34f9ce6177231d43cea3f77661b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / unref-0.1.1-py3-none-any.whl

Download URL unref-0.1.1-py3-none-any.whl
Size 50.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
df81388a729ae91d5315e732e6f11d5a9375c0ad219048d559de0094b97782f5
BLAKE2b-256 checksum
How to use checksums
8768e6c110207678c51fbcd944586f2167bb1b05f182d4a1da90ae6c54b5df36
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for unref 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page