Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

workon, mkvirtualenv and lsvirtualenv say command not found

Errorworkon: command not found

Short answer

workon is not a program on your PATH. virtualenvwrapper defines it as a shell function when its script, virtualenvwrapper.sh, is sourced. So the error means the script was never sourced, was sourced from the wrong path, or failed because PATH or the Python interpreter was not set first. Fix the lines in your shell startup file.

  • Applies to virtualenvwrapper 6.x, bash 5, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out whether the script exists and whether the current shell has loaded it.

    type workon
    pip show -f virtualenvwrapper | grep -i "virtualenvwrapper.sh"
  2. 2Match what you see, then jump to its fix

    1. 1type workon prints nothing, but virtualenvwrapper.sh exists on diskThe source line is missing from the shell startup fileFix
    2. 2No such file or directory when the shell starts, naming virtualenvwrapper.shThe source line points at the wrong placeFix
    3. 3The source line is right but the script cannot find python or virtualenv at startupPATH or the Python interpreter is set after the script loadsFix

What does the error look like?

  • workon: command not found
  • mkvirtualenv: command not found
  • bash: workon: command not found after a fresh terminal

Cause 1 of 3

The source line is missing from the shell startup file

1Check

pip only installs the files. The commands appear when the startup file of your shell sources virtualenvwrapper.sh. Look for the line.

grep -n virtualenvwrapper ~/.bashrc ~/.profile

2Fix

Add the variables and the source line to ~/.bashrc, then reload the file. The path after source must be where the script actually is.

export WORKON_HOME=$HOME/.virtualenvs
source /usr/local/bin/virtualenvwrapper.sh

3Verify

Reload the file and ask for the command again.

source ~/.bashrc
type workon

Confirmed by virtualenvwrapper.readthedocs.io

Did this fix it?

Cause 2 of 3

The source line points at the wrong place

1Check

The install page shows /usr/local/bin/virtualenvwrapper.sh but says your path may differ. A pip install with --user puts the script in your user directory (usually ~/.local), not /usr/local.

command -v virtualenvwrapper.sh
ls ~/.local/bin/virtualenvwrapper.sh

2Fix

Put the real path in the source line.

source ~/.local/bin/virtualenvwrapper.sh

3Verify

Open a new terminal and run workon with no arguments; it lists your environments (empty if you have none).

workon

Confirmed by virtualenvwrapper.readthedocs.io

Did this fix it?

Cause 3 of 3

PATH or the Python interpreter is set after the script loads

1Check

The script looks for python and virtualenv when it is sourced, so PATH must already be set. VIRTUALENVWRAPPER_PYTHON must be a full path and must also be set before the script is sourced.

grep -n -E "PATH|VIRTUALENVWRAPPER_PYTHON|virtualenvwrapper" ~/.bashrc
command -v python3

2Fix

Move the PATH and VIRTUALENVWRAPPER_PYTHON lines above the source line. Use the interpreter that has virtualenvwrapper installed.

export PATH="$HOME/.local/bin:$PATH"
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
export WORKON_HOME=$HOME/.virtualenvs
source ~/.local/bin/virtualenvwrapper.sh

3Verify

Open a new terminal and create a test environment.

mkvirtualenv test-env

Confirmed by virtualenvwrapper.readthedocs.io

Did this fix it?

How do I stop it coming back?

  • Install virtualenvwrapper into your base Python, not while a virtualenv is active.
  • Keep the three lines (PATH, VIRTUALENVWRAPPER_PYTHON, source) together and in that order in one startup file.
  • After moving to a new machine or a new Python, re-check the path in the source line.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.