Creosote

5.2.0 · active · verified Thu Apr 16

Creosote is a Python command-line tool designed to identify unused dependencies within a project's virtual environment. It helps prevent bloated environments by scanning Python files for imports and comparing them against the declared dependencies in various specification files like `pyproject.toml`, `requirements.txt`, PDM, and Pipenv. As of version 5.2.0, it is actively maintained with frequent releases, typically on a monthly to bi-monthly cadence.

Common errors

```
command not found: creosote
```
cause The `creosote` executable is not in your system's PATH. This typically happens if the package was not installed in the active virtual environment, or if the virtual environment's bin directory is not sourced.

fix Ensure `creosote` is installed in your active virtual environment (`pip install creosote`) and that the virtual environment is properly activated (`source .venv/bin/activate`). Alternatively, install it with `pipx install creosote` for global access.
```
Error: Python 3.9 is not supported. The minimum required version is now Python 3.10.
```
cause You are attempting to run Creosote version 5.0.0 or later on a Python 3.9 environment, which is no longer supported.

fix Upgrade your Python environment to 3.10 or newer. If you must use Python 3.9, install a compatible older version of Creosote, e.g., `pip install 'creosote<5.0.0'`.
```
Could not find any dependencies file at path: 'pyproject.toml' for sections 'project.dependencies'.
```
cause Creosote could not locate the specified dependency file or the given section within it. This might be due to an incorrect file path, a typo in the section name, or the file not existing.

fix Double-check the `--deps-file` path and the `--sections` argument for typos. Ensure the file exists and the section path is correct for your project's configuration (e.g., `project.dependencies` for PEP 621 or `tool.poetry.dependencies` for Poetry).

Warnings

breaking Creosote dropped support for Python 3.9 in version 5.0.0. Projects requiring Creosote must use Python 3.10 or newer.
Fix: Upgrade your Python environment to version 3.10 or higher. If unable to upgrade, use Creosote version <5.0.0.
gotcha When using `pyproject.toml` for dependency management, you must specify the correct section(s) where dependencies are declared using the `--sections` argument (e.g., `project.dependencies`, `tool.poetry.dependencies`). Omitting this will lead to Creosote not finding any declared dependencies.
Fix: Include `--sections` argument with the path to your dependency group, e.g., `--sections project.dependencies` or `--sections tool.poetry.dependencies`.
gotcha Creosote might miss imports that are deferred (i.e., imported inside functions or conditionally) by default. Use the `--include-deferred` flag to enable detection of these imports.
Fix: Add the `--include-deferred` flag to your Creosote command: `creosote ... --include-deferred`.
gotcha For Django projects, explicitly imported apps or middleware might not be recognized as used. Creosote provides a `--django-settings` option to scan `INSTALLED_APPS` and `MIDDLEWARE` in your settings file.
Fix: Use the `--django-settings` flag with the path to your Django settings module, e.g., `--django-settings myproject.settings`.

Install

pip install creosote Install with pip

Quickstart

This quickstart demonstrates how to install and run Creosote to identify an unused dependency in a simple project structure using `pyproject.toml`. It sets up a virtual environment, installs Creosote and a couple of dependencies (one used, one unused), then runs Creosote to find the unused one.

mkdir my_project
cd my_project
python -m venv .venv
source .venv/bin/activate
pip install creosote
pip install requests

# Create a dummy pyproject.toml
cat <<EOL > pyproject.toml
[project]
name = "my_project"
version = "0.1.0"
requires-python = ">=3.10"

[project.dependencies]
requests = ">=2.31.0,<3.0.0"
unused_lib = "==1.0.0"
EOL

# Create a dummy Python file that uses 'requests'
cat <<EOL > app.py
import requests

def fetch_data(url):
    response = requests.get(url)
    return response.text

if __name__ == "__main__":
    print("Fetching example.com...")
    fetch_data("https://example.com")
EOL

creosote --venv .venv --paths . --deps-file pyproject.toml --sections project.dependencies

view raw JSON →