8 releases (3 stable)
|2.0.2||Aug 1, 2021|
|2.0.0||Jul 18, 2021|
|0.1.5||Jan 15, 2021|
#929 in Development tools
49 downloads per month
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
venv were re-implemented in Rust instead.
Cargo and crates.io
- Install rust (https://www.rust-lang.org/tools/install).
- Add the
cargobin path to your
- Usually the bin path is
- Usually the bin path is
cargo install venv-wrapper.
You can install venv-wrapper from the AUR.
$ paru -S venv-wrapper-bin
$ brew install marier-nico/packages/venv-wrapper
- After installing, make sure you can use the
venv-wrappercommand (it should be in your shell's
- Then, you need to setup your shell to use venv-wrapper. To do this, edit your shell
startup configuration file (
~/.config/fish/config.fish) and add the following anywhere in there :
eval "$(venv-wrapper init bash)" venv completions # Optional, if you want shell completions
eval "$(venv-wrapper init zsh)" venv completions # Optional, if you want shell completions
venv-wrapper init fish | source venv completions # Optional, if you want shell completions
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
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.
The location for the configuration file depends on your platform of choice. For specific implementation details, see the directories crate.
The XDG user directory specification is followed. Assuming defaults, the configuration should be located in
The Standard Directories are used. By default, the configuration should be in
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
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
These shells are fully supported and should all work correctly :
However, all features except shell completions should work in most bash-like shells.
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.
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!
In its current state, this project does not quite match the features of
missing features are as follows :
- Copy virtualenvs
- Customizable hooks
- A plugin system to create shareable extensions
To release a new version, there a few simple steps to follow.
- Create or edit the
RELEASE_CHANGELOG.mdfile (at the repo's root) to contain a changelog for the release.
- This will be the GitHub release's body
- Update the version in
- Merge all code to be released into
- Create a new tag pointing to the head of the
git tag -s vX.Y.Z -m "Release vX.Y.Z"
- Push the new tag.
git push --tags
- After the release is created, update the homebrew formula here.