# reuse: a linter for the REUSE licensing recommendations

> The reuse tool checks whether a project follows the REUSE recommendations, which ask you to keep licence texts in a LICENSES directory and put an SPDX header on every file. Its own repository demonstrates the practice, and the release line is at 6.2.0 with the last push on 2026-10-13.

**fsfe/reuse-tool** — This is a mirror of https://codeberg.org/fsfe/reuse-tool

- Repository: https://github.com/fsfe/reuse-tool
- Website: https://reuse.software
- Stars: 596 · Forks: 163
- Language: Python
- License: not declared
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/fsfe-reuse-tool

## What compliance with REUSE 3.3 means

reuse is a tool for compliance with the REUSE recommendations, and the README states the current specification version as 3.3 with Python 3.10+.

The background section explains why the tool exists. Copyright and licensing is difficult, especially when reusing software from different projects that are released under various different licenses. REUSE was started by the Free Software Foundation Europe to provide a set of recommendations that make licensing your Free Software projects easier. The README makes two claims about that: the recommendations make it easier to declare the licences under which your works are released, and they make it easier for a computer to understand how your project is licensed.

The second claim is the one that matters in practice. The recommendations are threefold: choose and provide licenses, add copyright and licensing information to each file, and confirm REUSE compliance. That last step is what this tool does, and it is the step a machine can do for you.

The project points at three documents for more detail: a tutorial for a step-by-step guide through the three steps, an FAQ covering basic questions about licensing, copyright and more complex use cases, and the full specification for advanced users and integrators. The documentation lives at reuse.readthedocs.io and the site reuse.software, and the source is hosted on Codeberg at codeberg.org/fsfe/reuse-tool, with this repository described as a mirror of it.

## A deliberately small tool next to the larger ones

The README has a paragraph that is worth reading closely, because it is unusual for a project to bound itself this explicitly. It says there are other tools that have a lot more features and functionality surrounding the analysis and inspection of copyright and licenses in software projects, and that the REUSE tool, on the other hand, is solely designed to be a simple tool to assist in compliance with the REUSE recommendations.

That is a design statement, and it has consequences. The tool does not try to be a licence database, a compatibility checker or a report generator. It checks one thing: whether your project follows three rules, and it does that check the same way every time.

The project metadata shows the surrounding infrastructure that supports that narrowness. There is a REUSE status badge pointing at the project's own compliance check on api.reuse.software, a badge marking the README as standard-readme compliant, a repology packaging status badge showing which distributions ship the tool, and a Weblate translation status badge. Those are the badges of a project whose own housekeeping is part of its message.

The licensing note in the package metadata is also unusual. The licence field reads Apache-2.0 AND CC0-1.0 AND CC-BY-SA-4.0 AND GPL-3.0-or-later, which is a deliberate multi-licence offer rather than a single choice, and the classifiers list OSI Approved, DFSG approved and CC0 1.0 Universal.

## libmagic and version control are optional, and their absence changes results

The dependencies section is short, and then the caveats are specific enough to matter.

Unless you install through a package manager, it may help to be aware of the system dependencies of reuse: Python 3.10+, libmagic, and version control systems, namely Git, Mercurial 4.3+, Pijul, Jujutsu and Fossil. Excepting Python, these dependencies are all optional, and reuse will still work if they are not installed.

The consequences are stated, and they are not cosmetic. If a version control system is not installed, then reuse will not correctly ignore files which are ignored by the VCS, for example via .gitignore. If libmagic is not installed, then a slower mechanism will be used to detect the encodings of files, and you may need to explicitly install the fall-back, which is the charset-normalizer extra.

The extra is spelled reuse with the charset-normalizer extra in brackets, and the README gives pipx install with that extra as the example.

The VCS point is the one to internalise. A lint that reports files the repository already excludes is a lint that produces false findings, and a project with a busy .gitignore will see them. The list of supported version control systems is also broader than Git alone, which tells you the tool is used on projects that live in Mercurial, Pijul, Jujutsu or Fossil repositories.

The README also points at a list of the supported versions of Python on PyPI, so the exact interpreter range for a given release is checkable there.

## Four install routes, and the recommended one

Installation is documented in four ways, and the README marks the first two as recommended.

The package manager route is the most conventional. There are packages available for easy install on many operating systems, and the README invites you to help package the tool for more distributions. For Debian and derivatives it is a single apt install, and for Fedora and derivatives a single dnf install.

```bash
apt install reuse
```

```bash
dnf install reuse
```

An automatically generated list of available packages is published on repology.org, without any guarantee for completeness.

The pipx route is the other recommended one, and its one-liner both installs and runs the tool from PyPI.

```bash
pipx run reuse lint
```

The reason given is isolation: pipx automatically isolates reuse into its own Python virtualenv, so it will not interfere with other Python packages and they will not interfere with it. If you want reuse without prepending pipx run every time, you install it globally, and then it will be available in ~/.local/bin, which must be added to your PATH. On Windows the required path may look like %USERPROFILE%\AppData\Roaming\Python\Python310\Scripts, depending on the Python version installed. Upgrades are a pipx upgrade reuse.

The pip route installs into ~/.local/bin with pip3 install --user reuse, and the source route is pip install .. The README recommends the methods above instead, for easier and more stable updates.

## The workflow is three steps, and lint is the third

The usage section starts by telling you to read the REUSE tutorial, and then gives the short version.

You put your licenses in the LICENSES/ directory. You add a comment header to each file saying SPDX-License-Identifier: GPL-3.0-or-later, and SPDX-FileCopyrightText: $YEAR $NAME, and you can be flexible with the format as long as the line starts with SPDX-FileCopyrightText:. Then you verify your work using this tool.

The header format is shown with the tool's own licence as the example.

```
# SPDX-FileCopyrightText: 2017 Free Software Foundation Europe e.V. <https://fsfe.org>
#
# SPDX-License-Identifier: CC-BY-SA-4.0
```

The check itself is reuse lint, and the output ends with a line congratulating you on compliance with version 3.3 of the REUSE Specification.

The command set is larger than lint. The README lists annotate, which adds copyright and licensing information to the header of a file, download, which downloads the specified license into the LICENSES/ directory, lint, which verifies the project for REUSE compliance, and lint-file, which verifies a single file. The full documentation covers the rest.

## The project applies its own rules to itself

The repository is the best worked example of the tool, and it is worth reading as configuration rather than as code.

At the top level there is a LICENSES/ directory holding the licence texts, a REUSE.toml configuration file, a .reuse directory included in the source distribution, and SPDX headers on the files that need them. The pyproject.toml opens with four separate SPDX-FileCopyrightText lines and an SPDX-License-Identifier line, the Makefile does the same, and the Dockerfile carries its own header. The repository therefore demonstrates exactly the practice it asks others to adopt.

The Makefile has a target that lints the project with itself, and the comment explains the step that trips people up.

```makefile
reuse: dist ## check with self
	poetry run reuse lint
	tar -xf dist/reuse*.tar.gz -C dist/
	# This prevents the linter from using the project root as root.
	git init dist/reuse*/
	poetry run reuse --root dist/reuse*/ lint
```

The extracted source distribution is turned into its own git repository before being linted, so the linter does not treat the project root as the root of the tree it is checking. There is also a lint-third-party target that runs a script from the .forgejo directory to lint selected third-party repositories and compare with expected output, which is a regression test for the linter itself.

The Docker image tells you what the tool needs at runtime. It is built on alpine:3.22, installs git, mercurial, python3, openssh-client and libmagic, builds a wheel with poetry into a virtualenv, and then sets the entrypoint to reuse with the default command lint. It also runs git config --global --add safe.directory /data, because the container usually runs against a mounted repository.

## Where a licensing linter is the wrong tool

The first case is a small project with one licence and no per-file attribution need. A handful of files released under a single licence do not need an SPDX header on every file, and the linter would be ceremony. The value of reuse scales with the number of files and the number of distinct licences in a tree, and with the number of downstream consumers who need the information in a machine readable form.

The second case is a legal question. reuse checks that the declarations you wrote are complete and consistent with the REUSE rules. It does not tell you whether a licence is compatible with what you intend to do, and nothing in the documentation claims otherwise. The FAQ covers basic questions about licensing and copyright and more complex use cases, but the tool remains a checker of declarations rather than an adviser.

The third case is a project that needs a full SBOM rather than a compliance verdict. The tool's own topic tags include sbom and spdx, and it is worth being precise about what that means. The SPDX identifiers in the headers are the machine readable licensing information, and a tool that consumes those identifiers can assemble an SBOM, but reuse itself reports on compliance with a specification, not on the dependency tree of a build.

The alternative to weigh is the family of larger tools the README points to on reuse.software/comparison, which inspect and analyse copyright and licences in more depth. The difference in approach is the philosophy: those tools start from the project and infer what is licensed how, while REUSE starts from the declaration and checks that you have made one for every file. If you want to discover the licensing of a codebase you did not write, the other family is the right shape. If you want your own project to be unambiguous to both a person and a machine, that is what this tool is for.

## Conclusion

reuse suits a project with many files, mixed licences and downstream consumers who need machine readable licensing information, and it suits organisations that already publish an SBOM and want the licence side to line up with it. It does not suit a small project with one licence and no per-file attribution need, and it does not answer legal questions about whether a licence is compatible with your use. Verify first that libmagic and a version control system are present, because without them the tool will not correctly ignore VCS-ignored files and will fall back to a slower encoding detection path, and check which release you pin, since the newest tag is 6.2.0 from 2025.

## FAQ

### How do I install the reuse tool?

The README marks the package manager route and the pipx route as recommended. Package managers are apt install reuse for Debian and derivatives and dnf install reuse for Fedora and derivatives, and pipx has the one-liner pipx run reuse lint, with pipx install reuse for a permanent installation. There is also pip3 install --user reuse and pip install . from source.

### What does reuse lint check?

It verifies the project for compliance with the REUSE recommendations, whose three steps are choosing and providing licenses, adding copyright and licensing information to each file, and confirming compliance. The current specification version is 3.3, and a successful run ends by congratulating you on compliance with that version.

### What happens if libmagic or a version control system is missing?

Both are optional, but without a version control system reuse will not correctly ignore files ignored by the VCS, for example via .gitignore, and without libmagic a slower mechanism is used to detect file encodings. The fall-back encoding detector can be installed with the charset-normalizer extra, for example pipx install reuse[charset-normalizer].

### Which version control systems does reuse support?

Git, Mercurial 4.3 or newer, Pijul, Jujutsu and Fossil are listed as the supported version control systems, and the README notes that reuse still works if none of them is installed, only without correct ignore handling.

### Under what licence is the reuse tool released?

The package metadata records the licence as Apache-2.0 AND CC0-1.0 AND CC-BY-SA-4.0 AND GPL-3.0-or-later, and the classifiers list OSI Approved, DFSG approved and CC0 1.0 Universal. The repository itself is described as a mirror of the Codeberg project at codeberg.org/fsfe/reuse-tool.

## Sources

- [fsfe/reuse-tool on GitHub](https://github.com/fsfe/reuse-tool)
- [Issues](https://github.com/fsfe/reuse-tool/issues)
- [Project website](https://reuse.software)
- [README](https://github.com/fsfe/reuse-tool/blob/main/README.md)
- [Releases](https://github.com/fsfe/reuse-tool/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/fsfe-reuse-tool