Simple Python Virtual Environment Management

venv-wrapper is a convenient tool to help you manage your Python virtual environments. It used to be a wrapper around python's built-in venv module, but that is no longer the case, the required features from venv were re-implemented in Rust instead.

Installation

Cargo and crates.io

1. Install rust (https://www.rust-lang.org/tools/install).
2. Add the cargo bin path to your PATH environment variable.
   • Usually the bin path is ~/.cargo/bin.
3. Run cargo install venv-wrapper.

Arch Linux

You can install venv-wrapper from the AUR.

$ paru -S venv-wrapper-bin

Homebrew

$ brew install marier-nico/packages/venv-wrapper

PPA

Coming soon!

Getting Started

1. After installing, make sure you can use the venv-wrapper command (it should be in your shell's $PATH).
2. Then, you need to setup your shell to use venv-wrapper. To do this, edit your shell startup configuration file (~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish) and add the following anywhere in there :

Bash

eval "$(venv-wrapper init bash)"
venv completions # Optional, if you want shell completions

ZSH

eval "$(venv-wrapper init zsh)"
venv completions # Optional, if you want shell completions

Fish

venv-wrapper init fish | source
venv completions # Optional, if you want shell completions

Configuration

It's possible to configure venv-wrapper with either a configuration file, environment variables, or CLI flags.

Available Configuration Values

• venv_root: The directory in which to store all virtualenvs (defaults to ~/.virtualenvs).

Config File

Config Content

The config file is a simple ini file that contains no sections, like this :

venv_root = /home/me/.non-default-location

CAUTION: Paths in your configuration MUST be absolute, otherwise you might end up putting virtual environments where you don't intend to.

Config Location

The location for the configuration file depends on your platform of choice. For specific implementation details, see the directories crate.

• Linux

  The XDG user directory specification is followed. Assuming defaults, the configuration should be located in ~/.config/venv-wrapper/config.ini.

• macOS

  The Standard Directories are used. By default, the configuration should be in ~/Library/Application support/venv-wrapper/config.ini

Environment Variables

Note that paths do not need to be absolute here because your shell will perform path expansion. You do need the path to be absolute if your shell does not expand paths.

VENVWRAPPER_VENV_ROOT=~/.a-different-venvs-directory venv ls

CLI Flags

The same note as with environment variables applies here : no need for an absolute path unless your shell does not expand paths.

• venv -r ~/.a-different-venvs-directory venv ls

Shell Compatibility

These shells are fully supported and should all work correctly :

• Bash
• ZSH
• Fish

However, all features except shell completions should work in most bash-like shells.

Shell Completions

By default, shell completions are not active, but enabling them is really easy. All you have to do is run :

$ venv completions

Note: You must initialize venv-wrapper in your shell before activating completions.

Contributing

Getting Started

Mostly, you should install pre-commit and run pre-commit install to make sure your commits are up to stuff! Also, your commits should adhere to conventional commits. To do this, you can use a tool like commitizen, which will help make sure all commits look good.

The commit convention was added recently, so most commits are not yet compliant!

Missing Features

In its current state, this project does not quite match the features of virtualenvwrapper. The missing features are as follows :

• Copy virtualenvs
• Customizable hooks
• A plugin system to create shareable extensions

Releasing Versions

To release a new version, there a few simple steps to follow.

1. Create or edit the RELEASE_CHANGELOG.md file (at the repo's root) to contain a changelog for the release.
   • This will be the GitHub release's body
2. Update the version in cargo.toml, and src/cli/get_app.rs.
3. Merge all code to be released into main.
4. Create a new tag pointing to the head of the main branch.
   • git tag -s vX.Y.Z -m "Release vX.Y.Z"
5. Push the new tag.
   • git push --tags
6. After the release is created, update the homebrew formula here.