[Feature Request] Optional usage‑logging of `pyenv` activations (usage tracking)

[aksajja]

Description

pyenv manages Python versions well, but currently provides no way to track where a given version is being used across the filesystem. This feature request proposes optional, opt-in usage logging to help users gain visibility into Python version activations across their projects.

Problem

• There's no way to know which directories are using a specific Python version unless you manually search for .python-version files.
• pyenv does not track usage history, such as when or where a version was activated.
• This limits cleanup, auditing, and environment management.

Proposed Feature

Introduce opt-in usage logging, such that:

• Activations via pyenv activate, pyenv shell, or resolution of .python-version files trigger a log entry.
• Log entries are appended to a simple file (e.g., ~/.pyenv/usage.log) or stored in a configurable location.

Each log entry would include:

• Timestamp
• Python version or virtualenv name
• Full path of the directory where it was activated

Add optional commands:

• pyenv usage — Show all recent usage entries
• pyenv usage <version> — Show usage locations for a specific Python version

Benefits

• Helps users audit which projects are using which versions
• Enables cleanup of unused environments
• Assists in debugging path conflicts or version mismatches
• Fully backward-compatible — only enabled when opted in (e.g., PYENV_LOG_USAGE=1)

Suggested Implementation Notes

• Hook into shims or activation logic (e.g., pyenv shell, pyenv local, pyenv activate)
• Log format: newline-delimited JSON (ndjson) or simple tab-separated format
• Should not impact performance or fail workflows if the logger breaks
• Can be opt-in via PYENV_LOG_USAGE=1 or a config file toggle.

Environment

• pyenv version: 2.6.2
• OS: [macOS/Linux/Windows/etc.]
• Other plugins: [e.g., pyenv-virtualenv, pyenv-update, etc.]

Blockers / Concerns

• Determining where to store the logs
• Avoiding spam or rapid-fire entries (consider debounce logic or deduplication)
• Managing file size or rotation for long-lived systems

Related

No existing issue or discussion found addressing this directly.

[native-api]

This can be done with a plugin. pyenv activate has hook points both before and after activation.
See https://github.com/pyenv/pyenv/wiki/Authoring-plugins for the general information on composing plugins and pyenv-sh-activate source code in Pyenv-Virtualenv to see where exactly you can run your code.