VIRTUALENVWRAPPER(1)

📦
version 4.8.4 · 4 versions
, in debian bookworm, debian trixie, ubuntu jammy

🎀 virtualenvwrapper(1): the manual, but make it iconic 🎀

✨ NAME ✨

virtualenvwrapper, a set of wrappers that help you manage your python virtualenvs 💅

Everything below gets typed straight into the Terminal command line, bestie 💻

🌸 MANAGING ENVIRONMENTS 🌸

🧚 mkvirtualenv

Okay so mkvirtualenv creates a brand new environment inside your WORKON_HOME ✨

Syntax:

mkvirtualenv [-a project_path] [-i package] [-r requirements_file] [virtualenv options] ENVNAME

All options except -a, -i, -r, and -h get passed straight through to virtualenv. Once it's made, the new environment is automatically activated, so you're already in it 🫶

$ workon
$ mkvirtualenv mynewenv
New python executable in mynewenv/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(mynewenv)$ workon
mynewenv
(mynewenv)$
  • -a — link an existing project directory to your new environment so everything's one vibe 📁
  • -i — install one or more packages after the environment is created. Repeat the option to add more 📦
  • -r — point it at a text file listing the packages you want. The value gets passed to pip -r for installing 📜

SEE ALSO 🦋

  • scripts-premkvirtualenv
  • scripts-postmkvirtualenv
  • requirements file format

🌈 mktmpenv

Same energy as mkvirtualenv, but for a throwaway environment inside WORKON_HOME 🫧

Syntax:

mktmpenv [(-c|--cd)|(-n|--no-cd)] [VIRTUALENV_OPTIONS]

No naming stress here, because a unique virtualenv name gets generated for you automatically 🙈

If you use -c or --cd, the working directory switches to the virtualenv directory during the post-activate phase. This happens no matter what VIRTUALENVWRAPPER_WORKON_CD is set to.

If you use -n or --no-cd, the working directory stays put during the post-activate phase, again no matter what VIRTUALENVWRAPPER_WORKON_CD says.

$ mktmpenv
Using real prefix '/Library/Frameworks/Python.framework/Versions/2.7'
New python executable in 1e513ac6-616e-4d56-9aa5-9d0a3b305e20/bin/python
Overwriting 1e513ac6-616e-4d56-9aa5-9d0a3b305e20/lib/python2.7/distutils/__init__.py
with new content
Installing setuptools...............................................
....................................................................
.................................................................done.
This is a temporary environment. It will be deleted when deactivated.
(1e513ac6-616e-4d56-9aa5-9d0a3b305e20) $

👑 lsvirtualenv

Lists all of your environments. The main character list 📋

Syntax:

lsvirtualenv [-b] [-l] [-h]
  • -b — Brief mode, turns off the verbose output 🤫
  • -l — Long mode, turns the verbose output on. This is the default 📖
  • -h — prints the help for lsvirtualenv 🆘

SEE ALSO 🦋

  • scripts-get_env_details

🔍 showvirtualenv

Shows the details for one single virtualenv, so you can stalk it properly 👀

Syntax:

showvirtualenv [env]

SEE ALSO 🦋

  • scripts-get_env_details

🧹 rmvirtualenv

Removes an environment from WORKON_HOME. Bye bye 👋

Syntax:

rmvirtualenv ENVNAME
You have to use deactivate before removing the environment you're currently in. Don't be that person 💀
(mynewenv)$ deactivate
$ rmvirtualenv mynewenv
$ workon
$

SEE ALSO 🦋

  • scripts-prermvirtualenv
  • scripts-postrmvirtualenv

👯 cpvirtualenv

Duplicates an existing virtualenv. The source can be one that virtualenvwrapper already manages, or an external environment that was created somewhere else 🪞

WARNING: Copying virtual environments is not well supported 🚨 Each virtualenv has path information hard-coded into it, and there may be cases where the copy code doesn't realize it needs to update a particular file. Use with caution, bestie!

Syntax:

cpvirtualenv ENVNAME [TARGETENVNAME]

NOTE: A target environment name is required when you're duplicating within WORKON_HOME. You can skip it when importing external environments, though, and if you do, the new environment gets the same name as the original 🧃

$ workon
$ mkvirtualenv source
New python executable in source/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(source)$ cpvirtualenv source dest
Making script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/easy_install relative
Making script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/easy_install-2.6 relative
Making script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/pip relative
Script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/postactivate cannot be made relative (it's not a normal script that starts with #!/Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/python)
Script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/postdeactivate cannot be made relative (it's not a normal script that starts with #!/Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/python)
Script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/preactivate cannot be made relative (it's not a normal script that starts with #!/Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/python)
Script /Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/predeactivate cannot be made relative (it's not a normal script that starts with #!/Users/dhellmann/Devel/virtualenvwrapper/tmp/dest/bin/python)
(dest)$ workon
dest
source
(dest)$

SEE ALSO 🦋

  • scripts-precpvirtualenv
  • scripts-postcpvirtualenv
  • scripts-premkvirtualenv
  • scripts-postmkvirtualenv

🌍 allvirtualenv

Runs a command in all virtualenvs under WORKON_HOME. Full takeover energy 👑

Syntax:

allvirtualenv command with arguments

Each virtualenv gets activated (activation hooks get skipped), the working directory changes to the current virtualenv, and then your command runs. Commands can't change the current shell state, but they can change the virtualenv itself 🧚

$ allvirtualenv pip install -U pip

🎯 CONTROLLING THE ACTIVE ENVIRONMENT 🎯

🔄 workon

Lists or switches your working virtual environments. This is the one you'll use the most, periodt 💖

Syntax:

workon [(-c|--cd)|(-n|--no-cd)] [environment_name|"."]

If you don't give an environment_name, the list of available environments gets printed to stdout 📃

If you use -c or --cd, the working directory switches to the project directory during the post-activate phase, no matter what VIRTUALENVWRAPPER_WORKON_CD is set to.

If you use -n or --no-cd, the working directory stays where it is during the post-activate phase, again regardless of VIRTUALENVWRAPPER_WORKON_CD.

If you pass "." as the environment name, the name gets derived from the base name of your current working directory. Huge thanks to Matias Saguir for contributing this one 🫶

$ workon
$ mkvirtualenv env1
  New python executable in env1/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env1)$ mkvirtualenv env2
New python executable in env2/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env2)$ workon
env1
env2
(env2)$ workon env1
(env1)$ echo $VIRTUAL_ENV
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
(env1)$ workon env2
(env2)$ echo $VIRTUAL_ENV
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env2
(env2)$

SEE ALSO 🦋

  • scripts-predeactivate
  • scripts-postdeactivate
  • scripts-preactivate
  • scripts-postactivate
  • variable-VIRTUALENVWRAPPER_WORKON_CD

🛑 deactivate

Switches you out of a virtual environment and back to the system-installed version of Python 🌤️

Syntax:

deactivate

NOTE: This command actually comes from virtualenv, but it gets wrapped so it can have before and after hooks, just like workon does for activate 🎀

$ workon
$ echo $VIRTUAL_ENV

$ mkvirtualenv env1
New python executable in env1/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env1)$ echo $VIRTUAL_ENV
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
(env1)$ deactivate
$ echo $VIRTUAL_ENV

$

SEE ALSO 🦋

  • scripts-predeactivate
  • scripts-postdeactivate

✨ QUICKLY NAVIGATING TO A VIRTUALENV ✨

okay so there are two functions that give you shortcuts to hop straight into whatever virtualenv is currently active 🦋

cdvirtualenv

This one changes your current working directory to $VIRTUAL_ENV, which is the top of your virtualenv 🌸 You can also tack on an optional argument to the path, so you can dive right into a subdirectory in one move.

cdvirtualenv [subdir]
$ mkvirtualenv env1
New python executable in env1/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env1)$ echo $VIRTUAL_ENV
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
(env1)$ cdvirtualenv
(env1)$ pwd
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
(env1)$ cdvirtualenv bin
(env1)$ pwd
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1/bin

cdsitepackages

Okay this one is lowkey iconic 💅 The exact path to the site-packages directory depends on your Python version, so cdsitepackages is basically a shortcut for cdvirtualenv lib/python${pyvers}/site-packages so you don't have to remember it. You can also pass an optional argument to go even deeper into the site-packages directory.

cdsitepackages [subdir]
$ mkvirtualenv env1
New python executable in env1/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env1)$ echo $VIRTUAL_ENV
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1
(env1)$ cdsitepackages PyMOTW/bisect/
(env1)$ pwd
/Users/dhellmann/Devel/virtualenvwrapper/tmp/env1/lib/python2.6/site-packages/PyMOTW/bisect

lssitepackages

This one is giving "show me what's inside" 🔍 Calling lssitepackages lists the contents of the site-packages directory for whichever virtualenv is currently active.

lssitepackages
$ mkvirtualenv env1
New python executable in env1/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env1)$ $ workon env1
(env1)$ lssitepackages
setuptools-0.6.10-py2.6.egg     pip-0.6.3-py2.6.egg
easy-install.pth                setuptools.pth

✨ PATH MANAGEMENT ✨

add2virtualenv

Main character energy for sharing packages 🧚 Adds the directories you specify to the Python path for the currently-active virtualenv. Sometimes you want to share installed packages that live outside the system site-packages directory and that you don't want installed in every single virtualenv. You could symlink the source into the environment's site-packages, but it's also easy to add extra directories to the PYTHONPATH by putting them in a .pth file inside site-packages using add2virtualenv.

add2virtualenv directory1 directory2 ...

Here's how to do it, bestie 🎀

  1. Check out the source for a big project, such as Django.
  2. Run: add2virtualenv path_to_source.
  3. Run: add2virtualenv.
  4. A usage message and list of current "extra" paths gets printed.
  5. Use option -d to remove the added path.

The directory names get added to a path file named _virtualenv_path_extensions.pth inside the site-packages directory for the environment.

Based on a contribution from James Bennett and Jannis Leidel 🫶

toggleglobalsitepackages

This one is a switch and it's so satisfying 🔥 It controls whether the active virtualenv can access the packages in the global Python site-packages directory.

toggleglobalsitepackages [-q]

It outputs the new state of the virtualenv. If you want zero output, use the -q switch to turn off all of it 🤫

$ mkvirtualenv env1
New python executable in env1/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
(env1)$ toggleglobalsitepackages
Disabled global site-packages
(env1)$ toggleglobalsitepackages
Enabled global site-packages
(env1)$ toggleglobalsitepackages -q
(env1)$

✨ PROJECT DIRECTORY MANAGEMENT ✨

SEE ALSO: project-management 📚

mkproject

Okay this is the one for starting fresh 🌈 mkproject creates a new virtualenv in the WORKON_HOME and a project directory in PROJECT_HOME.

mkproject [-f|--force] [-t template] [virtualenv_options] ENVNAME
  • -f, --force — creates the virtualenv even if the project directory already exists, so you can live a little 🙈

The -t template option can be repeated to use several templates when making a new project. They get applied in the order you name them on the command line. Everything else gets passed straight to mkvirtualenv to create a virtual environment with the same name as the project 💖

$ mkproject myproj
New python executable in myproj/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
Creating /Users/dhellmann/Devel/myproj
(myproj)$ pwd
/Users/dhellmann/Devel/myproj
(myproj)$ echo $VIRTUAL_ENV
/Users/dhellmann/Envs/myproj
(myproj)$

SEE ALSO:

  • scripts-premkproject
  • scripts-postmkproject

setvirtualenvproject

This one is all about pairing things up 💜 setvirtualenvproject binds an existing virtualenv to an existing project. The arguments are the full paths to the virtualenv and the project directory. Once the association is made, when workon activates the virtualenv, the project gets activated too.

setvirtualenvproject [virtualenv_path project_path]
$ mkproject myproj
New python executable in myproj/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
Creating /Users/dhellmann/Devel/myproj
(myproj)$ mkvirtualenv myproj_new_libs
New python executable in myproj/bin/python
Installing setuptools.............................................
..................................................................
..................................................................
done.
Creating /Users/dhellmann/Devel/myproj
(myproj_new_libs)$ setvirtualenvproject $VIRTUAL_ENV $(pwd)

If you don't give it any arguments, it assumes the current virtualenv and the current directory 🦋

Any number of virtualenvs can point at the same project directory, which makes it super easy to hop between Python versions or other dependencies for testing ✨

cdproject

Change the current working directory to whatever is set as the project directory for the active virtualenv 🗺️

cdproject

✨ MANAGING INSTALLED PACKAGES ✨

wipeenv

⚠️ bestie, this one is a big deal 💀 wipeenv removes all of the installed third-party packages in the current virtualenv. Use it with intention!
wipeenv

✨ OTHER COMMANDS ✨

virtualenvwrapper

When you need a little reminder, this one has your back 🧸 It prints a list of commands and their descriptions as basic help output.

virtualenvwrapper

2009-2019, Doug Hellmann 💜

That's the whole page, bestie 💅 Version 4.8.4, dated Sep 03, 2019, and it's still giving 🌸 Now go make a virtualenv and slay 🎀✨

📦 where this page comes from