mirror of
https://github.com/pyenv/pyenv-virtualenv.git
synced 2025-11-08 11:33:55 -05:00
387f627464
Some checks failed
tests / tests (macos-13) (push) Has been cancelled
tests / tests (macos-14) (push) Has been cancelled
tests / tests (macos-15) (push) Has been cancelled
tests / tests (ubuntu-22.04) (push) Has been cancelled
tests / tests (ubuntu-24.04) (push) Has been cancelled
283 lines
10 KiB
Markdown
283 lines
10 KiB
Markdown
# 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 <name>
|
|
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.
|