How to create a virtual environment in Python

A Python virtual environment keeps one project's dependencies, console scripts, and interpreter path separate from the base installation. That isolation helps prevent package upgrades, test installs, or build tools from changing the Python runtime used by other projects or by operating-system tooling.

The built-in venv module creates a directory such as .venv that contains its own Python executable, activation scripts, private site-packages tree, and a pyvenv.cfg file that records the base interpreter. Current upstream Python documentation also notes that pip is bootstrapped by default and that activation is optional because commands can call the environment's interpreter directly.

A POSIX shell with python3 is assumed, and the environment directory is named .venv. If a distro-managed interpreter reports that ensurepip is unavailable, install the matching package that provides virtual-environment support first, such as python3-venv on Debian or Ubuntu. On Windows, use py -m venv .venv and the scripts under .venv\Scripts, and recreate the environment instead of copying or moving it because installed scripts keep absolute interpreter paths.

1. Change to the project directory where the virtual environment should be created.

   $ cd ~/inventory-service

   Keeping the environment inside the project directory makes it easier to pair the interpreter with the correct source tree and dependency files.

2. Confirm which Python interpreter will build the environment.

   $ python3 --version
   Python 3.14.3

   Use the same interpreter command that will run the project, such as python or py when python3 is not the local command name.

   Related: How to check Python version

3. Create the virtual environment in a dedicated directory such as .venv.

   $ python3 -m venv .venv

   The command normally returns no output on success and bootstraps pip into the environment unless --without-pip is used.

   Add --upgrade-deps when the new environment should immediately update pip from PyPI instead of keeping only the bundled bootstrap version.

   If Debian or Ubuntu reports that ensurepip is unavailable, install the matching python3-venv package for that interpreter and rerun the command.

4. Inspect the new environment directory to confirm the expected files were created.

   $ ls -A .venv
   .gitignore
   bin
   include
   lib
   pyvenv.cfg

   Current Python releases create a .gitignore file in the environment by default; use --without-scm-ignore-files if that behavior is not wanted. On Windows, the scripts and interpreter are created under .venv\Scripts instead of .venv/bin.

5. Review the pyvenv.cfg file to verify which base interpreter created the environment and whether system packages are isolated.

   $ sed -n '1,4p' .venv/pyvenv.cfg
   home = /usr/local/bin
   include-system-site-packages = false
   version = 3.14.3
   executable = /usr/local/bin/python3.14

   The exact home and executable paths depend on how the base interpreter was installed, but include-system-site-packages = false remains the default isolated mode. Use --system-site-packages only when the environment must inherit packages from the base interpreter.

6. Verify that the new environment can run its own interpreter and bundled pip without activating the shell.

   $ ./.venv/bin/python -m pip --version
   pip 26.0 from /home/ops/inventory-service/.venv/lib/python3.14/site-packages/pip (python 3.14)
   $ ./.venv/bin/python -c 'import sys; print(sys.prefix != sys.base_prefix)'
   True

   The path after from shows which environment owns pip, and a True result confirms that the interpreter is running from the virtual environment without activation.