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.
• **Pyright and LSP Integration**: Optionally reloads `pyright` or `lsp-mode` after environment activation to resolve broken imports and ensure correct environment settings.
• **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)

LSP and Pyright Integration

The package provides optional integration with `lsp-mode` and `pyright`, automatically reloading the language server when changing virtual environments. This ensures that the Python environment settings are correctly updated, avoiding issues with unresolved imports.

To enable this feature, set auto-virtualenv-reload-lsp to t (the default setting):

(setq auto-virtualenv-reload-lsp t)

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.
• auto-virtualenv-reload-lsp: Automatically reloads `lsp-mode` or `pyright` upon virtual environment change to ensure consistent environment settings.

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.