Virtualfish comes in-built with a number of plugins.
You can use them by passing their names in as arguments to the virtualfish
loader in your
eval (python -m virtualfish auto_activation global_requirements)
Virtualenvwrapper Compatibility Aliases (
This plugin provides some global commands to make virtualfish behave more like Doug Hellman’s virtualenvwrapper.
vf activate <envname>
mkvirtualenv [<options>] <envname>=
vf new [<options>] <envname>
vf tmp [<options>]
vf rm <envname>
With this plugin enabled,
virtualfish can automatically activate a virtualenv when you are in a
certain directory. To configure it to do so, change to the directory,
activate the desired virtualenv, and run
This will save the name of the virtualenv to the file
will then look for this file every time you
cd into the directory (or
pushd, or anything else that modifies
When this plugin is enabled, ensure any modifications to your
config.fish happen before virtualfish is loaded.
vf connect- Connect the current virtualenv to the current directory, so that it is activated automatically as soon as you enter it (and deactivated as soon as you leave).
.venv) - the name of the file virtualfish will use for the auto-activation feature. Earlier versions of virtualfish used
VF_AUTO_ACTIVATED- If the currently-activated virtualenv was activated automatically, set to the directory that triggered the activation. Otherwise unset.
Global Requirements (
Keeps a global
requirements.txt file that is applied to every existing and
vf requirements- Edit the global requirements file in your
$EDITOR. Applies the requirements to all virtualenvs on exit.
This plugin adds project management capabilities, including automatic directory switching upon virtual environment activation. Typically a project directory contains files — such as source code managed by a version control system — that are often stored separately from the virtual environment.
The following example will create a new project, with a matching virtual
environment, both named
vf project YourProject
The above command performs the following tasks:
- creates new empty project directory in
PROJECT_HOME(if there is no existing
YourProjectdirectory within) and changes the current working directory to it
- creates new virtual environment named
YourProjectand activates it
To work on an existing project, use the
vf workon <name> command to activate
the specified virtual environment and change the current working directory to
the project of the same name. For cases in which the project name differs from
the target virtualenv name, you can manually specify which virtualenv should be
activated for a given project by creating a
.venv file inside the project
root containing the name of the corresponding virtualenv.
vf project <name>- Create a new project and matching virtual environment with the specified name. This name must be the last parameter (i.e., after
-p python3or any other arguments destined for the
mkprojectis aliased to this command.
vf workon <name>- Search for a project and/or virtualenv matching the specified name. If found, this activates the appropriate virtualenv and switches to the respective project directory. If
workonis aliased to this command.
vf lsprojects- List projects available in
vf cdproject- Search for a project matching the name of the currently activated virtualenv. If found, this switches to the respective project directory. If
cdprojectis aliased to this command.
~/projects/) - Where to create new projects and where to look for existing projects.
Environment Variables (
This plugin provides the ability to automatically set environment variables
when a virtual environment is activated. The environment variables are stored
.env file by default. This can be configured by setting
VIRTUALFISH_ENVIRONMENT_FILE to the desired file name. When using the
Projects (projects) plugin, the env file is stored in the project
directory unless it is manually created in the
$VIRTUAL_ENV directory. If
the projects plugin isn’t being used, the file is stored in the
When the virtualenv is activated, the values in the env file will be added to
the environment. If a variable with that name already exists, that value is
When the virtual environment is deactivated, if there was a pre-existing value it is returned to the environment. Otherwise, the variable is erased.
The format of the env file is one key-value set per line separated by an
Empty lines are ignored, as are any lines that start with
#. See the
# This is a valid comment and declaration FOO=bar # The empty line above is valid BAR=baz # A following comment like this is NOT okay
vf environment- Open the env file for the active virtual environment in
viif neither variable is set.
Update Python (
This plugin adds commands to change the python interpreter of the current virtual environment.
vf update_python [<python_exe>]- Remove the current virtual environment and create a new one with
VIRTUALFISH_DEFAULT_PYTHONif it is set, or the first executable named
PATH), and then reinstall all packages in the same versions with pip.
vf fix_python [<python_exe>]- Test the current python executable on the current virtual environment. If it doesn’t work, update it with
vf update_python [<python_exe>]. This may be usefull when one of your system’s python executable is updated, and some of your virtual environments are broken: you probably just need to run
vf all vf fix_python.
python) - The python interpreter to use if not specified on the command line.