How to initialise a Python virtual environment using venv

1. Objective:

To guide users in setting up a new Python virtual environment using the venv module, ensuring Python and venv are correctly installed, and placing the environment in a specified project directory.

2. Steps:

Step 1: Verify Python Installation

Confirm that Python is installed and accessible from the command line.

Open a terminal or command prompt.

Type the following command and press Enter:

python --version

Confirm the output displays the installed Python version. If Python is not installed, it is recommended to download and install the latest version from the official Python website. On Ubuntu, it is recommended to use pyenv to manage Python versions. See "How to install Python using pyenv" for more information.

Step 2: Verify venv Module Availability

Check if the venv module is included in your Python installation.

Run the following command in the terminal:

python -m venv --help

If the help message for venv appears, the module is available. If an error appears, you may need to install Python with the full standard library or use a Python distribution that includes venv.

Step 3: Navigate to the project directory

Navigate to the directory of the project where you want to create the virtual environment.

cd path/to/project_directory

If the project directory does not exist, create it using the mkdir command.

mkdir project_directory
cd project_directory

Step 4: Create the Virtual Environment

Initialize a new virtual environment in the project directory.

Run the following command:

python -m venv venv

This creates a subdirectory named venv within the project directory, containing the virtual environment files.

Step 5: Activate the Virtual Environment

Enable the virtual environment for use in your current terminal session.

Use the appropriate command for your operating system:

  • Windows:
venv\Scripts\activate
  • macOS/Linux:
source venv/bin/activate

Once activated, the terminal prompt will change to indicate the virtual environment is active (e.g., (venv)).

Step 6: Deactivate the Virtual Environment (Optional)

Exit the virtual environment when finished.

Simply type:

deactivate

The terminal prompt will return to its normal state.

3. Additional Information:

Tips:

  • To install packages within the virtual environment, ensure it is activated and use pip install package_name.
  • Use pip freeze > requirements.txt to save installed packages to a file for later use.
  • Sometimes you need to use python3 instead of python depending on your system configuration.
  • You might need to update pip and setuptools within the virtual environment using python -m pip install --upgrade pip setuptools. You can also do it when creating the environment by adding the --upgrade-deps flag to the python -m venv venv command.
  • To remove the virtual environment, delete the venv directory.

Warnings:

  • Always activate the virtual environment before running project-specific scripts to ensure dependencies are isolated.
  • Avoid modifying files directly inside the venv directory.