### CHANGELOG ## Version History ## v1.4.0 * Fix POSIX sh (dash) compatibility in pyenv-virtualenv-init by @chrisolof in https://github.com/pyenv/pyenv-virtualenv/pull/526 * Improve performance and output of `pyenv virtualenvs` by @samdoran in https://github.com/pyenv/pyenv-virtualenv/pull/502 ## v1.3.0 * CI: cleanup by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/521 * CI: tests: use Bats 1.10; support concurrent, out-of-order and multiple-times execution of stub commands; fix race condition between concurrent stubs by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/520 * Drastically speed up precommand hook by caching active version to skip redundant `activate` calls by @jakelodwick in https://github.com/pyenv/pyenv-virtualenv/pull/523 ## v1.2.6 * Fix changelog and version numbers ## v1.2.5 * Add prompt customization by @jimenezj8 in https://github.com/pyenv/pyenv-virtualenv/pull/476 * README: fix and distinguish syntax highlighting in Bash vs Fish snippets by @diericx in https://github.com/pyenv/pyenv-virtualenv/pull/489 * Fix pyenv-virtualenv using a different Python version in a conda environment by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/492 * Fix confusing activate/deactivate error messages when Pyenv is not installed as a shell function by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/495 * Fix errorneously creating a symlink inside env directory if running w… by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/496 * Update LICENSE, fix copyright license year by @JasonnnW3000 in https://github.com/pyenv/pyenv-virtualenv/pull/499 * docs: add WSL note about core.autocrlf to prevent CRLF issues by @stoneHee99 in https://github.com/pyenv/pyenv-virtualenv/pull/512 * docs: fix the link to Pyenv shell setup steps by @cshen-dev in https://github.com/pyenv/pyenv-virtualenv/pull/516 * Convert issue template to new Github format by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/519 * Prevent loss of data on `virtualenv-delete -f` if the env doesn't exist and the PREFIX envvar is set elsewhere by @SabriRamadanTNG in https://github.com/pyenv/pyenv-virtualenv/pull/518 ## v1.2.4 * Fix failing to detect `-m venv` when "python" is not provided by the distro by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/479 * README: Remove dollar signs from commands that are meant to be copied by @galonsky in https://github.com/pyenv/pyenv-virtualenv/pull/481 * Reflect pyenv-latest switch change in 2.4.8 by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/484 ## v1.2.3 * Fix: add `colorize` helper by @silverjam in https://github.com/pyenv/pyenv-virtualenv/pull/470 * Bump pyenv-virtualenv reporting version to match release by @ushuz in https://github.com/pyenv/pyenv-virtualenv/pull/471 * Add fish prompt changing by @romirk in https://github.com/pyenv/pyenv-virtualenv/pull/475 * Don't activate if a 3rd-party venv is activated over ours by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/478 ## v1.2.2 * Prompt removal was never done and is not planned anymore by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/447 * Update PYENV_VIRTUALENV_VERSION by @jack-mcivor in https://github.com/pyenv/pyenv-virtualenv/pull/449 * Add activate/deactivate hooks by @joshfrench in https://github.com/pyenv/pyenv-virtualenv/pull/452 * More helpful error message when requesting a nonexistent base version by @MarcinKonowalczyk in https://github.com/pyenv/pyenv-virtualenv/pull/454 * Add fish install oneliner by @ElijahLynn in https://github.com/pyenv/pyenv-virtualenv/pull/322 * Link python*-config into VE by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/460 ## v1.2.1 * Support prefixes resolved by pyenv-latest as base version names by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/446 ## v1.2.0 * ~/.*rc should be modified instead of ~/.*profile by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/384 * Fixes #394 - update pyenv virtualenvs to list virtualenvs start with dot prefixes by @Gauravtalreja1 in https://github.com/pyenv/pyenv-virtualenv/pull/395 * Fix installation steps to allow for Pyenv 2 by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/388 * Fix get-pip.py URLs for older versions of Python by @jivanf in https://github.com/pyenv/pyenv-virtualenv/pull/403 * Add (y/N) prompt help text by @sh-cho in https://github.com/pyenv/pyenv-virtualenv/pull/404 * perf(sh-activate): avoid a pyenv-version-name call by @scop in https://github.com/pyenv/pyenv-virtualenv/pull/380 * Fix unbound variable errors when running `pyenv activate` with `set -u` Use default empty value. This fixes #422. by @ackalker in https://github.com/pyenv/pyenv-virtualenv/pull/423 * Fix another unbound variable error by @ackalker in https://github.com/pyenv/pyenv-virtualenv/pull/424 * Update `get-pip.py` URLs in `pyenv-virtualenv` by @mcdonnnj in https://github.com/pyenv/pyenv-virtualenv/pull/426 * Deduplicate shims in $PATH for the fish shell during initialization by @ericvw in https://github.com/pyenv/pyenv-virtualenv/pull/430 * Upgrade uninstall hook after pyenv/pyenv#2432 by @laggardkernel in https://github.com/pyenv/pyenv-virtualenv/pull/438 * Stop delete force failing when virtualenv does not exist by @eganjs in https://github.com/pyenv/pyenv-virtualenv/pull/330 * fix: relative path to pyenv-realpath.dylib by @scop in https://github.com/pyenv/pyenv-virtualenv/pull/378 * Spelling fixes by @scop in https://github.com/pyenv/pyenv-virtualenv/pull/352 * Clone bats with --depth=1, gitignore it by @scop in https://github.com/pyenv/pyenv-virtualenv/pull/351 * set -u fixes by @scop in https://github.com/pyenv/pyenv-virtualenv/pull/350 * Set up Github Actions CI by @native-api in https://github.com/pyenv/pyenv-virtualenv/pull/440 * Enhance documentation about options for `pyenv virtualenv` by @pylipp in https://github.com/pyenv/pyenv-virtualenv/pull/425 * Return control to pyenv-uninstall in uninstall/envs.bash by @aiguofer in https://github.com/pyenv/pyenv-virtualenv/pull/321 * Use realpath of scripts to determine relative locations by @andrew-christianson in https://github.com/pyenv/pyenv-virtualenv/pull/308 * Shell detect improvements by @scop in https://github.com/pyenv/pyenv-virtualenv/pull/377 ## v1.1.5 * Fix install script (#290, #302) ## v1.1.4 * Support newer conda (#290) * Prefer `python3.x` executable if available (#206, #282, #296) ## v1.1.3 * No code changes since 1.1.2 ## v1.1.2 * Use custom get-pip URL based on the target version (#253, #254, #255) * Source conda 4.4.4 shell files (#251) * Evaluate force flag before testing if venv exists (#232) ## v1.1.1 * Set `CONDA_PREFIX` to make is useable in conda activate/deactivate scripts (#224) * Generate `pydoc` executable after creating new virtualenv (#197, #230) ## v1.1.0 * fish: use "set -gx" instead of "setenv" (#215, #216, #217, #218) ## v1.0.0 * Use similar versioning scheme as pyenv; YYYYMMDD -> X.Y.Z ## v20160716 * Suppress activate/deactivate messages by default (#169, #170, #171) * Source conda package activate/deactivat scripts if exist (#173) * Use `source` in favor of `.` for `fish` (#175) * Use `python -m venv` instead of `pyvenv` due to deprecation of `pyvenv` after 3.6 (#184, #185) ## v20160315 * Evaluate `${PATH}` when outputted code is eval'd. (#154) * Set proper `CONDA_DEFAULT_ENV` for shorter name (#160) ## v20160202 * Install virtualenv 13.1.2 for CPython/Stackless 3.2.x (yyuu/pyenv#531) ## v20160112 * Fix problem with `virtualenv` to look up executables from source version with `--system-site-packages` (#62) ## v20151229 * Fix `deactivate` error on `fish` (#136) ## v20151222 * Improved interoperability with Anaconda/Miniconda (#103, #106, #107, #108) * Create `virtualenv` inside `envs` directory of source version, like Anaconda/Miniconda (#103, #107) * Rewrite `pyenv activate` and `pyenv deactivate` without using scripts provided by virtualenv and conda (#51, #69, #103, #104, #121) * Improve the `pyenv activate` behaviour on multiple versions (#105, #111) * Reject creating a virtualenv named `system` (yyuu/pyenv#475) * Add `--skip-aliases` to `pyenv virtualenvs` (#120) * Stop showing `version not installed` warning messages in precmd (#49) ## v20151103 * Passing return value from executed command. (#100) * Add workaround for commands installed in a virtual environment created by `pyvenv` (#62) * init: zsh: prepend hook to `precmd_functions` (#101) ## v20151006 * Ignore user's site-packages on ensurepip/get-pip (#89) * Find `python-config` from source version if current version is a virtualenv * Fix pyenv-virtualenv-init script for fish where command was in string and not being evaluated (#98) * Add foolproof for `-p` argument. (yyuu/pyenv#98) ## v20150719 * Add support for `conda` environments created by Anaconda/Miniconda (#91) * Look up commands for original version as well if the environment is created with `--system-site-packages` (#62) * Add error message if the source version is not installed (#83) ## v20150526 * Use `typeset -g` with `precmd_functions` (#75) * activate: display setup instructions only with `PYENV_VIRTUALENV_INIT=0` (#78) * Ignore failure of pyenv activate (#68) ## v20150119 * Ignore errors from `pyenv-version-name` since it might fail if there is configuration error (yyuu/pyenv#291) * The _shell_ version set in `activate` should be unset in `deactivate` (#61) * Anaconda has `activate` script nevertheless it is not a virtual environment (#65) ## v20141106 * Stop creating after `ensurepip` since it has done by `ensurepip` itself * Suppress some useless warnings from `pyenv virtualenv-init` ## v20141012 * Fix warnings from `shellcheck` to improve support for POSIX sh (#40) * Do not allow whitespace in `VIRTUALENV_NAME` (#44) * Should not persist `PYENV_DEACTIVATE` after automatic deactivation (#47, #48) ## v20140705 * Display information on auto-(de)?activation * Support manual (de)?activation with auto-activation enabled (#32, #34) * Exit as error when (de)?activation failed * Use https://bootstrap.pypa.io/ to install setuptools and pip * Create backup of original virtualenv within `$(pyenv root)/versions` when `--upgrade` ## v20140615 * Fix incompatibility issue of `pyenv activate` and `pyenv deactivate` (#26) * Workaround for the issue with pyenv-which-ext (#26) ## v20140614 * Add `pyenv virtualenv-init` to enable auto-activation feature (#24) * Create symlinks for executables with version suffix (yyuu/pyenv#182) ## v20140602 * Use new style GH raw url to avoid redirects (raw.github.com -> raw.githubusercontent.com) * Repaired virtualenv activation and deactivation for the fish shell (#23) ## v20140421 * Display error if `pyenv activate` was invoked as a command * Fix completion of `pyenv activate` (#15) * Use `virtualenv` instead of `pyvenv` if `-p` has given (yyuu/pyenv#158) ## v20140123 * Add `activate` and `deactivate` to make `pyenv-virtualenv` work with [jedi](https://github.com/davidhalter/jedi) (#9) * Use `ensurepip` to install `pip` if it is available * Unset `PIP_REQUIRE_VENV` to avoid problem on the installation of `virtualenv` (#10) * Add tests ## v20140110.1 * Fix install script ## v20140110 * Support environment variables of `EZ_SETUP` and `GET_PIP`. * Support a short option `-p` of `virtualenv`. ## v20131216 * Use latest release of setuptools and pip if the version not given via environment variables. ## v20130622 * Removed bundled `virtualenv.py` script. Now pyenv-virtualenv installs `virtualenv` package into source version and then use it. * On Python 3.3+, use `pyvenv` as virtualenv command if `virtualenv` is not available. * Install setuptools and pip into environments created by `pyvenv`. ## v20130614 * Add `pyenv virtualenvs` to list all virtualenv versions. * *EXPERIMENTAL*: Add `--upgrade` option to re-create virtualenv with migrating packages ## v20130527 * Remove `python-virtualenv` which was no longer used. * Change the installation path of the `virtualenv.py` script. (`./libexec` -> `./libexec/pyenv-virtualenv/${VIRTUALENV_VERSION}`) * Download `virtualenv.py` if desired version has not been installed. ## v20130507 * Display virtualenv information in `--help` and `--version` * Update virtualenv version; 1.8.4 -> 1.9.1 ## v20130307 * Rename the project; `s/python-virtualenv/pyenv-virtualenv/g` * The `pyenv-virtualenv` script is not depending on `python-virtualenv` now. `python-virtualenv` will left for compatibility and will not continue for future releases. * Update virtualenv version; 1.8.2 -> 1.8.4 ## v20130218 * Add pyenv 0.2.x (rbenv 0.4.x) style help messages. ## v20121023 * Create virtualenv with exact name of python executables. * Changed command-line options of python-virtualenv. First argument should be a path to the python executable. * Add install script. ## v20120927 * Initial public release. --- ### README # pyenv-virtualenv [](https://gitter.im/yyuu/pyenv-virtualenv?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [](https://travis-ci.org/pyenv/pyenv-virtualenv) pyenv-virtualenv is a [pyenv](https://github.com/pyenv/pyenv) plugin that provides features to manage virtualenvs and conda environments for Python on UNIX-like systems. (NOTICE: If you are an existing user of [virtualenvwrapper](http://pypi.python.org/pypi/virtualenvwrapper) and you love it, [pyenv-virtualenvwrapper](https://github.com/pyenv/pyenv-virtualenvwrapper) may help you (additionally) to manage your virtualenvs.) ## Installation ### Installing as a pyenv plugin This will install the latest development version of pyenv-virtualenv into the `$(pyenv root)/plugins/pyenv-virtualenv` directory. **Important note:** If you installed pyenv into a non-standard directory, make sure that you clone this repo into the 'plugins' directory of wherever you installed into. From inside that directory you can: - Check out a specific release tag. - Get the latest development release by running `git pull` to download the latest changes. 💡 **WSL note:** If you're using WSL, we recommend setting Git to use Unix-style line endings to prevent script execution errors: ```sh git config --global core.autocrlf input ``` 1. **Check out pyenv-virtualenv into plugin directory** ```bash git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv ``` For the Fish shell: ```fish git clone https://github.com/pyenv/pyenv-virtualenv.git (pyenv root)/plugins/pyenv-virtualenv ``` 2. (OPTIONAL) **Add `pyenv virtualenv-init` to your shell** to enable auto-activation of virtualenvs. This is entirely optional but pretty useful. See "Activate virtualenv" below. ```bash echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc ``` **Fish shell note**: Add this to your `~/.config/fish/config.fish` ```fish status --is-interactive; and pyenv virtualenv-init - | source ``` **Zsh note**: Modify your `~/.zshrc` file instead of `~/.bashrc`. 3. **Restart your shell to enable pyenv-virtualenv** ```bash exec "$SHELL" ``` ### Installing with Homebrew (for macOS users) macOS users can install pyenv-virtualenv with the [Homebrew](https://brew.sh) package manager. This will give you access to the `pyenv-virtualenv` command. If you have pyenv installed, you will also be able to use the `pyenv virtualenv` command. *This is the recommended method of installation if you installed pyenv with Homebrew.* ```sh brew install pyenv-virtualenv ``` Or, if you would like to install the latest development release: ```sh brew install --HEAD pyenv-virtualenv ``` After installation, you'll still need to do [Pyenv shell setup steps](https://github.com/pyenv/pyenv#b-set-up-your-shell-environment-for-pyenv) then add ```sh eval "$(pyenv virtualenv-init -)" ``` to your shell's `.rc` file (as stated in the caveats). You'll only ever have to do this once. ## Usage ### Using `pyenv virtualenv` with pyenv To create a virtualenv for the Python version used with pyenv, run `pyenv virtualenv`, specifying the Python version you want and the name of the virtualenv directory. For example, ```sh pyenv virtualenv 2.7.10 my-virtual-env-2.7.10 ``` will create a virtualenv based on Python 2.7.10 under `$(pyenv root)/versions` in a folder called `my-virtual-env-2.7.10`. `pyenv virtualenv` forwards any options to the underlying command that actually creates the virtual environment (`conda`, `virtualenv`, or `python -m venv`). See the output of `pyenv virtualenv --help` for details. ### Create virtualenv from current version If there is only one argument given to `pyenv virtualenv`, the virtualenv will be created with the given name based on the current pyenv Python version. ```sh $ pyenv version 3.4.3 (set by /home/yyuu/.pyenv/version) $ pyenv virtualenv venv34 ``` ### List existing virtualenvs `pyenv virtualenvs` shows you the list of existing virtualenvs and `conda` environments. ```sh $ pyenv shell venv34 $ pyenv virtualenvs miniconda3-3.9.1 (created from /home/yyuu/.pyenv/versions/miniconda3-3.9.1) miniconda3-3.9.1/envs/myenv (created from /home/yyuu/.pyenv/versions/miniconda3-3.9.1) 2.7.10/envs/my-virtual-env-2.7.10 (created from /home/yyuu/.pyenv/versions/2.7.10) 3.4.3/envs/venv34 (created from /home/yyuu/.pyenv/versions/3.4.3) my-virtual-env-2.7.10 (created from /home/yyuu/.pyenv/versions/2.7.10) * venv34 (created from /home/yyuu/.pyenv/versions/3.4.3) ``` There are two entries for each virtualenv, and the shorter one is just a symlink. ### Activate virtualenv Some external tools (e.g. [jedi](https://github.com/davidhalter/jedi)) might require you to `activate` the virtualenv and `conda` environments. If `eval "$(pyenv virtualenv-init -)"` is configured in your shell, `pyenv-virtualenv` will automatically activate/deactivate virtualenvs on entering/leaving directories which contain a `.python-version` file that contains the name of a valid virtual environment as shown in the output of `pyenv virtualenvs` (e.g., `venv34` or `3.4.3/envs/venv34` in example above) . `.python-version` files are used by pyenv to denote local Python versions and can be created and deleted with the [`pyenv local`](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-local) command. You can also activate and deactivate a pyenv virtualenv manually: ```sh pyenv activate pyenv deactivate ``` ### Delete existing virtualenv Removing the directories in `$(pyenv root)/versions` and `$(pyenv root)/versions/{version}/envs` will delete the virtualenv, or you can run: ```sh pyenv uninstall my-virtual-env ``` You can also delete existing virtualenvs by using `virtualenv-delete` command, e.g. you can run: ```sh pyenv virtualenv-delete my-virtual-env ``` This will delete virtualenv called `my-virtual-env`. ### virtualenv and venv There is a [venv](http://docs.python.org/3/library/venv.html) module available for CPython 3.3 and newer. It provides an executable module `venv` which is the successor of `virtualenv` and distributed by default. `pyenv-virtualenv` uses `python -m venv` if it is available and the `virtualenv` command is not available. ### Anaconda and Miniconda You can manage `conda` environments by `conda create` as same manner as standard Anaconda/Miniconda installations. To use those environments, you can use `pyenv activate` and `pyenv deactivate`. ```sh $ pyenv version miniconda3-3.9.1 (set by /home/yyuu/.pyenv/version) $ conda env list # conda environments: # myenv /home/yyuu/.pyenv/versions/miniconda3-3.9.1/envs/myenv root * /home/yyuu/.pyenv/versions/miniconda3-3.9.1 $ pyenv activate miniconda3-3.9.1/envs/myenv discarding /home/yyuu/.pyenv/versions/miniconda3-3.9.1/bin from PATH prepending /home/yyuu/.pyenv/versions/miniconda3-3.9.1/envs/myenv/bin to PATH $ python --version Python 3.4.3 :: Continuum Analytics, Inc. $ pyenv deactivate discarding /home/yyuu/.pyenv/versions/miniconda3-3.9.1/envs/myenv/bin from PATH ``` If `conda` is available, `pyenv virtualenv` will use it to create environment by `conda create`. ```sh $ pyenv version miniconda3-3.9.1 (set by /home/yyuu/.pyenv/version) $ pyenv virtualenv myenv2 $ conda env list # conda environments: # myenv /home/yyuu/.pyenv/versions/miniconda3-3.9.1/envs/myenv myenv /home/yyuu/.pyenv/versions/miniconda3-3.9.1/envs/myenv2 root * /home/yyuu/.pyenv/versions/miniconda3-3.9.1 ``` You can use version like `miniconda3-3.9.1/envs/myenv` to specify `conda` environment as a version in pyenv. ```sh $ pyenv version miniconda3-3.9.1 (set by /home/yyuu/.pyenv/version) $ pyenv shell miniconda3-3.9.1/envs/myenv $ which python /home/yyuu/.pyenv/versions/miniconda3-3.9.1/envs/myenv/bin/python ``` ### Special environment variables You can set certain environment variables to control pyenv-virtualenv. * `PYENV_VIRTUALENV_CACHE_PATH`, if set, specifies a directory to use for caching downloaded package files. * `VIRTUALENV_VERSION`, if set, forces pyenv-virtualenv to install the desired version of virtualenv. If `virtualenv` has not been installed, pyenv-virtualenv will try to install the given version of virtualenv. * `GET_PIP`, if set and `venv` is preferred over `virtualenv`, use `get_pip.py` from the specified location. * `GET_PIP_URL`, if set and `venv` is preferred over `virtualenv`, download `get_pip.py` from the specified URL. * `PIP_VERSION`, if set and `venv` is preferred over `virtualenv`, install the specified version of pip. * `PYENV_VIRTUALENV_VERBOSE_ACTIVATE`, if set, shows some verbose outputs on activation and deactivation * `PYENV_VIRTUALENV_PROMPT`, if set, allows users to customize how `pyenv-virtualenv` modifies their shell prompt. The default prompt ("(venv)") is overwritten with any user-specified text. Specify the location of the virtual environment name with the string `{venv}`. For example, the default prompt string would be `({venv})`. ## Version History See [CHANGELOG.md](CHANGELOG.md). ### License [(The MIT License)](LICENSE) * Copyright (c) 2015 Yamashita, Yuu Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ---