Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

Automatically activate python virtualenv on Emacs
https://github.com/marcwebbie/auto-virtualenv

Last synced: about 1 month ago
JSON representation

Automatically activate python virtualenv on Emacs

Awesome Lists containing this project

README 

        
#+TITLE: auto-virtualenv.el - Seamless Python Virtualenv Activation in Emacs

#+AUTHOR: Marcwebbie

#+URL: https://github.com/marcwebbie/auto-virtualenv

#+DESCRIPTION: Automatically activate Python virtual environments 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:

#+BEGIN_SRC emacs-lisp

(package-install 'auto-virtualenv)

#+END_SRC



** Manual Installation

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

#+BEGIN_SRC shell

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

#+END_SRC

Then add it to your Emacs configuration:

#+BEGIN_SRC emacs-lisp

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

(require 'auto-virtualenv)

#+END_SRC



** Using ~use-package~

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

#+BEGIN_SRC emacs-lisp

(use-package auto-virtualenv

  :load-path "path/to/auto-virtualenv"

  :config

  (setq auto-virtualenv-verbose t)

  (auto-virtualenv-setup))

#+END_SRC



** Using ~straight.el~

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

#+BEGIN_SRC emacs-lisp

(straight-use-package

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



(require 'auto-virtualenv)

(setq auto-virtualenv-verbose t)

(auto-virtualenv-setup)

#+END_SRC



* 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):

#+BEGIN_SRC emacs-lisp

(setq auto-virtualenv-reload-lsp t)

#+END_SRC



* 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:

#+BEGIN_SRC emacs-lisp

(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"))

#+END_SRC



* Related Projects and Inspirations

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

- [[https://github.com/jorgenschaefer/pyvenv][pyvenv]]: Manually activates and deactivates virtual environments.

- [[https://github.com/purcell/exec-path-from-shell][exec-path-from-shell]]: Syncs Emacs environment variables with the shell.

- [[https://github.com/bbatsov/projectile][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.