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.nameor__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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.