12.3. Module venv

  • Isolated Python environment

  • Allows to have multiple versions of Python for one project

  • For testing on different versions: python3.12, python3.13, python3.14

  • Test libraries and frameworks before upgrading (create venv, install requirements, run tests, delete if fails)

  • Allows to have different versions of libraries and frameworks for each project

  • Difference between venv and virtualenv

  • venv is bundled with Python since 3.3 (no installation required)

  • virtualenv is independent package installed via pip

  • virtualenvwrapper is additionally installed command line tools

12.3.1. Venv vs. Virtualenv

Both venv and virtualenv are used to create isolated Python environments. Since Python 3.3, a subset of virtualenv has been integrated into the standard library under the venv module.

Both venv and virtualenv:

  • Author: Bernat Gabor

  • Support: Python 3

Module venv:

  • Python: version 3 only

  • Install: not required - bundled with Python since Python 3.3

  • Usage: python3.13 -m venv DIRECTORY

  • Development: synchronized with Python releases

  • Features: all you need

Module virtualenv:

  • Python: version 2 and 3

  • Install: pip install virtualenv

  • Usage: virtualenv DIRECTORY

  • Development: independent from Python releases

  • Features: all from venv plus extra (which typically you don't need)

In my opinion builtin venv is all you need. Moreover no installation is required to use it.

12.3.2. Create

  • venv-py313 is the name of venv folder

  • See "Directory Naming Convention" below

Create virtual environment in directory named venv-py313:

$ python3.13 -m venv venv-py313

12.3.3. Run Ad-Hoc

  • Will run python with from virtual environment

  • With all the modules already installed

Run myscript.py using virtual environment:

$ venv-py313/bin/python3 myscript.py

12.3.4. Activate

  • bin for macOS, Linux, BSD

  • Scripts for Windows

  • Note the direction of slash and backslash (OS dependent)

There is a slight difference between activating virtual environment on macOS, Linux, BSD and Windows.

Linux, macOS, BSD:

$ source venv-py313/bin/activate

Windows:

$ venv-py313\Scripts\activate.bat

12.3.5. Install Modules Ad-Hoc

Install new module:

$ venv-py313/bin/python -m pip install MODULE

Install modules listed in requirements.txt

$ venv-py313/bin/python -m pip install -r requirements.txt

Upgrade modules listed in requirements.txt:

$ venv-py313/bin/python -m pip install --upgrade -r requirements.txt

List installed modules:

$ venv-py313/bin/python -m pip freeze

12.3.6. Directory Naming Convention

  • No standard naming convention

  • Naming directory like module (venv) name is a good idea

  • Adding Python version is also a good practice

  • Optionally naming per main framework/library version

  • Dot at the beginning hides directory on Linux and macOS (but doesn't work on Windows)

  • Underscore is Python convention for private/protected, but does not work for OS and Git

venv  # may be confused with ``venv`` Python module, mind: ``sys.path``
venv-py
venv-py311
venv-py312
venv-py313
venv-py313-dj42
venv-py313-dj51
venv-py313-dj52
venv-py313-np126
venv-py313-np20
venv-py313-np21
venv-py313-np126-pd22
venv-py313-np21-pd22
venv-py314a1
venv-py314b1
venv-py314rc1

12.3.7. Good Practices

  • python3.13 -m venv -h

  • python3.13 -m venv --upgrade-deps venv-py313

  • Name venv directory similar to python version venv-py3.13

  • Place in your project directory

  • Add venv directory to .gitignore (important!)

  • Change prompt by appending at the end of venv-3.13/bin/activate:

12.3.8. Bash Prompt

  • Default on most Linux distributions

  • \e[ – This string tells bash prompt to apply color from next character.

  • 0;32m – This string represents the colors. The number before the; represent typeface. And the number after the ; represent color code.

  • \e[0m – This string will tell the bash prompt to apply the color to the previous character.

Typeface:

  • 0 – Normal

  • 1 – Bold

  • 2 – Dim

  • 4 – Underlined

Color codes:

  • 30 – Black

  • 31 – Red

  • 32 – Green

  • 33 – Brown

  • 34 – Blue

  • 35 – Purple

  • 36 – Cyan

  • 37 – Light gray

Define variables for Bash colors:

blue='\e[0;34m'
brown='\e[0;33m'
cyan='\e[0;36m'
gray='\e[0;37m'
green='\e[0;32m'
purple='\e[0;35m'
red='\e[0;31m'
white='\e[0;39m'

Set Bash prompt:

export PS1="\n${cyan}myproject> ${white}"

12.3.9. Zsh Prompt

  • Default on macOS

  • Colors: black, blue, cyan, green, magenta, red, white, yellow

export PROMPT="%F{cyan}myproject> %F{white}"

Optionally you can also set options:

setopt PROMPT_CR
setopt PROMPT_SP
export PROMPT_EOL_MARK=""

12.3.10. Shebang

Using #!/usr/bin/env python3 in a shebang line has several advantages over #!/usr/bin/python3:

  • Portability: #!/usr/bin/env python3 searches the PATH environment variable to locate the Python interpreter, allowing scripts to be more portable across different systems. It ensures that the correct version of Python specified by the environment is used, rather than relying on a hardcoded path that may vary between systems.

  • Virtual Environments: When working with virtual environments, using #!/usr/bin/env python3 ensures that the interpreter within the virtual environment is used. This allows scripts to utilize dependencies and configurations specific to the virtual environment, rather than the system-wide Python interpreter.

  • Flexibility: The env command allows for flexibility in specifying the Python interpreter. For example, if a script is designed to work with Python 3.12 but is executed on a system with Python 3.13 installed, #!/usr/bin/env python3 will use the correct version without needing to modify the shebang line.

  • Avoids Hardcoding Paths: Hardcoding the path to the Python interpreter (#!/usr/bin/python3) can lead to issues if the interpreter is located in a different directory on the target system. Using #!/usr/bin/env python3 avoids this problem by dynamically locating the interpreter based on the environment.

Overall, #!/usr/bin/env python3 provides a more flexible and portable solution for specifying the Python interpreter in a shebang line, making scripts easier to maintain and distribute across different environments.

12.3.11. Further Reading

12.3.12. Assignments

# %% License
# - Copyright 2025, Matt Harasymczuk <matt@python3.info>
# - This code can be used only for learning by humans
# - This code cannot be used for teaching others
# - This code cannot be used for teaching LLMs and AI algorithms
# - This code cannot be used in commercial or proprietary products
# - This code cannot be distributed in any form
# - This code cannot be changed in any form outside of training course
# - This code cannot have its license changed
# - If you use this code in your product, you must open-source it under GPLv2
# - Exception can be granted only by the author

# %% Run
# - PyCharm: right-click in the editor and `Run Doctest in ...`
# - PyCharm: keyboard shortcut `Control + Shift + F10`
# - Terminal: `python -m doctest -v myfile.py`

# %% About
# - Name: Virtualenv
# - Difficulty: easy
# - Lines: 0
# - Minutes: 2

# %% English
# 1. Create `venv` for newest Python version
# 2. Add `venv` as a Python interpreter in your IDE
# 3. Run doctests - all must succeed

# %% Polish
# 1. Stwórz `venv` dla najnowszej wersji Python
# 2. Dodaj `venv` jako interpreter Python w Twoim IDE
# 3. Uruchom doctesty - wszystkie muszą się powieść