VirtualFish Documentation Release 2.5.2 Leigh Brenecki, Justin Mayer, and contributors Jun 29, 2021 Contents 1 Contents 3 1.1 Installation and Setup..........................................3 1.2 Usage...................................................4 1.3 Plugins..................................................6 1.4 Extending VirtualFish.......................................... 10 1.5 Frequently Asked Questions....................................... 11 1.6 See Also................................................. 12 2 Contributors 13 i ii VirtualFish Documentation, Release 2.5.2 VirtualFish is a Python virtual environment manager for the Fish shell. Contents 1 VirtualFish Documentation, Release 2.5.2 2 Contents CHAPTER 1 Contents 1.1 Installation and Setup 1.1.1 Installing 1. Make sure you are running Fish 3.1+. If you are running an Ubuntu LTS release that has an older Fish version, install Fish via the Fish 3.x release series PPA. 2. The easiest way to install VirtualFish is by running: python -m pip install --user virtualfish. If you’re using Pipx, it is better to use: pipx install virtualfish. 3. Install the VirtualFish loader by running: vf install If you want to use VirtualFish with plugins, list the names of the plugins as arguments to the install command: vf install compat_aliases projects environment Note: After performing the above step, you will be prompted to run exec fish in order to make these changes active in your current shell session. 4. Customize your fish_prompt 1.1.2 Customizing Your fish_prompt VirtualFish doesn’t attempt to mess with your prompt. Since Fish’s prompt is a function, it is both much less straight- forward to change it automatically, and much more convenient to simply customize it manually to your liking. The easiest way to add the active virtual environment’s name to your prompt is to type funced fish_prompt and add the following line somewhere: 3 VirtualFish Documentation, Release 2.5.2 if set -q VIRTUAL_ENV echo -n -s(set_color -b blue white) "("(basename"$VIRTUAL_ENV") ")"(set_color ,!normal)"" end Then, type funcsave fish_prompt to save your new prompt to disk. 1.1.3 Un-installing To un-install VirtualFish, run: vf uninstall python -m pip uninstall virtualfish 1.2 Usage 1.2.1 Commands • vf new [<options>] <envname> - Create a virtual environment. • vf ls [--details] - List the available virtual environments. • vf activate <envname> - Activate a virtual environment. (Note: Doesn’t use the activate.fish script provided by Virtualenv.) • vf deactivate - Deactivate the current virtual environment. • vf upgrade [<options>] [<envname(s)>] - Upgrade virtual environment(s). • vf rm <envname> - Delete a virtual environment. • vf tmp [<options>] - Create a temporary virtual environment with a randomly generated name that will be removed when it is deactivated. • vf cd - Change directory to currently-activated virtual environment. • vf cdpackages - Change directory to currently-active virtual environment’s site-packages. • vf globalpackages - Toggle system site packages. • vf addpath - Add a directory to this virtual environment’s sys.path. • vf all <command> - Run a command in all virtual environments sequentially. • vf connect [<envname>] - Connect the current working directory with the currently active (or specified) virtual environment. This requires the auto-activation plugin to be enabled in order to have any effect besides creating a .venv file in the current directory. If you are accustomed to virtualenvwrapper commands (workon, etc.), you may wish to enable the Virtualenvwrapper Compatibility Aliases (compat_aliases) plugin. 1.2.2 Using Different Pythons By default, the environments you create with VirtualFish will use the same Python version that was originally used to Pip-install VirtualFish, which will usually be your system’s default Python interpreter. 4 Chapter 1. Contents VirtualFish Documentation, Release 2.5.2 If you want to create a new virtual environment with a different Python interpreter, add the --python PYTHON_EXE (-p for brevity) flag to vf new, where PYTHON_EXE is any Python executable. For example: vf new -p /usr/bin/python3 my_python3_env Specifying the full path to the Python executable avoids ambiguity and is thus the most reliable option, but if the target Python executable is on your PATH, you can save a few keystrokes and pass the bare executable instead: vf new -p pypy my_pypy_env Sometimes there may be Python interpreters on your system that are not on your PATH, with full filesystem paths that are long and thus hard to remember and type. VirtualFish makes dealing with these easier by automatically detecting and using Python interpreters in a few known situations, in the following order: 1. asdf Python plugin is installed and has built the specified Python version. 2. Pyenv is installed and has built the specified Python version. 3. Pythonz is installed and has built the specified Python version. 4. Homebrew keg-only versioned Python executable (e.g., 3.8) found at: /usr/local/opt/[email protected]/ bin/python3.8 For asdf, Pyenv, and Pythonz , in addition to passing option flags such as -p python3.8 or -p python3.9.0a4, you can even get away with specifying just the version numbers, such as -p 3.8 or -p 3.9.0a4. 1.2.3 Upgrading Virtual Environments Virtual environments contain links to Python interpreters that can become outdated over time. In addition, sometimes the underlying Python interpreter can be removed by Python upgrades, putting the virtual environment into an unusable state. Thankfully, VirtualFish includes a mechanism for upgrading outdated/broken environments. To understand which environments might be outdated/broken, run: vf ls --details VirtualFish compares environment Python versions to the current default Python version, as specified by the VIRTUALFISH_DEFAULT_PYTHON variable (see below), if defined. To perform a minor (point-release) upgrade to the currently-active virtual environment, run: vf upgrade Minor point-release upgrades will modify in-place the virtual environment’s Python version number and symlinks. (While this should work correctly in the majority of cases, there is the possibility that future changes to virtual envi- ronment structure will interfere with this in-place upgrade.) For major version upgrades, say from Python 3.8.x to 3.9.x, you must instead re-build the environment via: vf upgrade --rebuild Re-building an environment will record its current package versions, remove the old environment, create a new envi- ronment with the same name, and re-install the list of recorded package versions. If VirtualFish determines that a virtual environment is in a broken state, it will re-build that environment, even if --rebuild is omitted. To upgrade to a specific Python interpreter or version, use the --python option: 1.2. Usage 5 VirtualFish Documentation, Release 2.5.2 vf upgrade --rebuild --python /usr/local/bin/python3.8 Virtual environments need not be active in order to upgrade them. To upgrade one or more virtual environments, specify their names: vf upgrade project1 project2 Upgrades can also be applied to all environments. To re-build all existing environments: vf upgrade --rebuild --all 1.2.4 Configuration Variables The vf install [...] installation step writes the VirtualFish loader to a file at $XDG_CONFIG_HOME/fish/ conf.d/virtualfish-loader.fish, which on most systems defaults to: ~/.config/fish/conf.d/ virtualfish-loader.fish You can edit this file to, for example, change the plugin loading order. You can also add the following optional variables at the top, so that they are set before virtual.fish is sourced. • VIRTUALFISH_HOME (default: ~/.virtualenvs) - where all your virtual environments are kept. • VIRTUALFISH_DEFAULT_PYTHON - The default Python interpreter to use when creating a new virtual en- vironment; the value should be a valid argument to the Virtualenv --python flag. Regardless of the changes that you make, you must run exec fish afterward if you want those changes to take effect for the current shell session. 1.3 Plugins VirtualFish comes with a number of built-in plugins. You can use them by passing their names as arguments to the vf install command when installing for the first time. For example, the following will activate the compat_aliases, projects, and environment plugins: vf install compat_aliases projects environment To add or remove plugins after installation, use the vf addplugins and vf rmplugins commands. For exam- ple, the following will activate the auto_activation and projects plugins, and the subsequent command will remove the projects plugin: vf addplugins auto_activation projects vf rmplugins projects 1.3.1 Virtualenvwrapper Compatibility Aliases (compat_aliases) This plugin provides some global commands to make VirtualFish behave more like Doug Hellman’s virtualenvwrap- per. 6 Chapter 1. Contents VirtualFish Documentation, Release 2.5.2 Commands • workon <envname> = vf activate <envname> • deactivate = vf deactivate • mkvirtualenv [<options>] <envname> = vf new [<options>] <envname> • mktmpenv [<options>] = vf tmp [<options>] • rmvirtualenv = vf rm <envname> • lsvirtualenv = vf ls • cdvirtualenv = vf cd • cdsitepackages = vf cdpackages • add2virtualenv = vf addpath • allvirtualenv = vf all • setvirtualenvproject = vf connect 1.3.2 Auto-activation (auto_activation) 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 vf connect. This will save the