poetry-cache

Display Poetry's available caches

$ poetry cache list

$ poetry cache clear PyPI --all

$ poetry cache clear [pypi]:[requests]:[2.24.0]

poetry cache [options] [arguments]

clear
    Clears specified entries or the entire Poetry cache. Use with the --all option and a <cache-type> pattern.

list
    Lists the types and entries currently stored in Poetry's cache.

--all
    (Used with clear subcommand) Clears all entries for the specified cache type pattern.

<cache-type>
    (Argument for clear subcommand) A pattern or specific type of cache to clear (e.g., `pypi`, `wheels`, `src`).

The poetry cache command is a crucial utility within the Poetry ecosystem, designed to manage Poetry's internal cache of downloaded packages and other artifacts. This cache is essential for efficient dependency resolution and installation, as it stores distributions (like wheels and source distributions) from PyPI and other configured repositories, along with metadata related to virtual environments. By caching these assets, Poetry can significantly reduce network traffic and installation times on subsequent runs.

Users leverage `poetry cache` for several key purposes: to free up disk space by clearing old or unused cache entries, to resolve potential issues caused by corrupted or outdated cached files, or to force fresh downloads of dependencies. It provides subcommands like clear to remove specific cache types or entries, and list to inspect the current contents and types of the cache. Understanding and utilizing `poetry cache` helps maintain a clean, performant, and reliable development environment, especially when working with numerous projects or frequently updating dependencies. It prevents redundant downloads and ensures that Poetry operates with the most relevant and uncorrupted data available.

Clearing the cache can sometimes lead to longer installation times as packages need to be re-downloaded from remote repositories. Exercise caution when using `poetry cache clear --all <cache-type>` as it permanently removes all matching entries. The specific cache types (e.g., `pypi`, `wheels`, `src`) that are recognized by Poetry may evolve with different versions of the tool. Importantly, `poetry cache` is a subcommand of `poetry` and is not a standalone system utility; it requires Poetry to be installed and accessible in your environment.

Poetry's cache directories are typically located within the user's home directory, under operating system-specific paths (e.g., `~/.cache/pypoetry` on Linux, `~/Library/Caches/pypoetry` on macOS, or `%LOCALAPPDATA%/pypoetry/Cache` on Windows). The exact location can be influenced or overridden by the `POETRY_CACHE_DIR` environment variable. These directories store downloaded package distributions and other transient data.

While the `clear` subcommand often refers to `pypi` (for packages downloaded from PyPI) and `wheels` (for compiled wheel distributions), other types like `src` (for source distributions) might also be managed. The `list` subcommand is the best way to discover the currently recognized cache types and their contents within your Poetry environment.

The `poetry cache` subcommand was introduced as Poetry matured, providing users with essential control over the tool's internal caching mechanisms. Its development was driven by the need to address common issues such as managing disk space, resolving corrupted package installations, and ensuring efficient dependency workflows. This functionality has been a stable and integral part of Poetry's CLI for several major versions, reflecting the importance of cache management in modern dependency tools.

poetry(1), pip cache(1), npm cache(1), yarn cache(1)