auto-virtualenv.el - Seamless Python Virtualenv Activation in Emacs

Introduction

auto-virtualenv.el is an Emacs package that automatically activates Python virtual environments based on the project you’re working in. It detects both local (e.g., `.venv`) and global (e.g., `~/.pyenv/versions/`) environments, simplifying the process of switching between projects with distinct environments. It provides minimal mode line updates to maintain Emacs performance.

Features

**Automatic Environment Activation**: Activates the appropriate virtual environment upon entering a project.
**Clear Mode Line Indicators**: Displays the active environment in the mode line or shows “Venv: N/A” when none is active.
**Customizable Directories**: Searches both local and global directories for virtual environments.
**Minimal Mode Line Updates**: Avoids frequent resets for smoother Emacs performance.

Installation

From MELPA

To install from MELPA, use the following command:

(package-install 'auto-virtualenv)

Manual Installation

Clone the repository and add auto-virtualenv.el to your load path:

git clone https://github.com/marcwebbie/auto-virtualenv.git

Then add it to your Emacs configuration:

(add-to-list 'load-path "/path/to/auto-virtualenv")
(require 'auto-virtualenv)

Using `use-package`

Set up auto-virtualenv.el with use-package:

(use-package auto-virtualenv
  :load-path "path/to/auto-virtualenv"
  :config
  (setq auto-virtualenv-verbose t)
  (auto-virtualenv-setup))

Using `straight.el`

If you use straight.el, configure it as follows:

(straight-use-package
  '(auto-virtualenv :type git :host github :repo "marcwebbie/auto-virtualenv"))

(require 'auto-virtualenv)
(setq auto-virtualenv-verbose t)
(auto-virtualenv-setup)

Customization Options

The package provides customizable options to adapt to your project structure:

auto-virtualenv-global-dirs: Directories to search for virtual environments by project name.
auto-virtualenv-python-project-files: Files that identify a Python project (e.g., requirements.txt, setup.py).
auto-virtualenv-activation-hooks: Hooks that trigger virtual environment activation (default: find-file-hook and projectile-after-switch-project-hook).
auto-virtualenv-verbose: Enable verbose output for debugging.

Example configuration:

(setq auto-virtualenv-global-dirs
      '("~/.virtualenvs/" "~/.pyenv/versions/" "~/.envs/" "~/.conda/" "~/.conda/envs/"))
(setq auto-virtualenv-python-project-files
      '("requirements.txt" "Pipfile" "pyproject.toml" "setup.py" "manage.py" "tox.ini" ".flake8"))

Related Projects and Inspirations

auto-virtualenv.el was inspired by several other projects, including:

pyvenv: Manually activates and deactivates virtual environments.
exec-path-from-shell: Syncs Emacs environment variables with the shell.
projectile: A project management and navigation tool for Emacs.

License

This project is licensed under the GPLv3.

Contributions

Contributions are welcome! Feel free to open issues, submit pull requests, or suggest improvements.

marcwebbie/auto-virtualenv