Installing and using virtualenv with Python 3

 

Overview

This article explains how to use Python 3 to install the virtualenv tool on a DreamHost server.

Prerequisites

This article assumes you have Created a Shell user and are able to log into your server via SSH.

What is virtualenv?

Virtualenv is a tool used to create an isolated Python environment. This environment has its own installation directories that do not share libraries with other virtualenv environments (and optionally doesn't access the globally installed libraries either).

Virtualenv is the recommended way to configure a custom Python environment.

Difference between virtualenv and venv

The primary difference is that virtualenv offers more functionality than venv. Although you can create a virtual environment using venv with Python3, it's recommended that you install and use virtualenv instead.

See this page for a list of features venv does not offer compared to virtualenv.

Installing virtualenv using pip3

When working with virtual environments in Python, it's recommended you install a custom version of Python rather than the server's version. You can then use pip3 to install virtualenv locally.

  1. Log into your server via SSH.
  2. Install a custom version of Python 3, which also contains pip3.
  3. Confirm it's installed and active by running the which python3 command as shown in the article. This should return the path of your custom version of Python 3.
  4. Run the following command to upgrade pip3.
    [server]$ python3 -m pip install --upgrade pip
  5. Install virtualenv using pip3.
    [server]$ pip3 install virtualenv
    Collecting virtualenv Downloading virtualenv-15.1.0-py2.py3-none-any.whl (1.8MB) 100% |████████████████████████████████| 1.8MB 367kB/s Installing collected packages: virtualenv Successfully installed virtualenv-15.1.0
  6. Run the following command to view the full path to your custom version of virtualenv.
    [server]$ which virtualenv
    /home/username/opt/python-3.10.1/bin/virtualenv

Creating a virtual environment using a custom Python version

The following steps create a new virtual environment using your custom version of Python.

These steps use Python version 3.10.1. Make sure to use the version you installed.

  1. Make a note of the full file path to the custom version of Python you just installed above by running which python3.
    [server]$ which python3
    /home/username/opt/python-3.10.1/bin/python
  2. Navigate to your site's directory, where you'll create the new virtual environment:
    [server]$ cd ~/example.com
  3. Update your .bash_profile
    [server]$ . ~/.bash_profile
  4. Create the virtual environment using your custom version of Python. The following command creates a virtualenv named venv and uses the -p flag to specify the full path to the Python3 version you just installed:

    You can name the virtualenv anything you like.

    [server]$ virtualenv -p /home/username/opt/python-3.10.1/bin/python3 venv

    You may see the following error when installing.

    setuptools pip failed with error code 1` error

    If so, run the following:

    [user@localhost]$ pip3 install --upgrade setuptools

    Try again, and you should be able to install without an error.

How to use the virtualenv

This section explains how to activate your virtualenv, install packages, and then deactivate or delete it when you no longer need it.

Activating the virtualenv

To use your virtualenv, you must first activate it by running the source command. Run the following in the directory where you installed the virtualenv.

[server]$ source venv/bin/activate
The prompt changes where the name of the current virtual environment appears to the left. For example:
(venv) [server]$ 

Verify the correct Python version is active:

[server]$ python -V
Python 3.10.1

Any package that you install using pip is now placed in the virtual environment's project folder, isolated from the global Python installation.

Installing custom modules

See this article for instructions on how to use pip to install Python modules.

Deactivating the virtualenv

When finished working in the virtual environment, run the deactivate command to return to your shell user's environment.

[server]$ deactivate

Deleting the virtual environment

If you no longer need the virtualenv, you can delete it by simply deleting the project folder. For example:

[server]$ rm -rf venv

Troubleshooting

Use the full path to your custom virtualenv

It's possible that when you run the virtualenv command, it responds with the server version outside of your custom installation. Run the following command to confirm the full path to your Python3 virtualenv.

[server]$ which virtualenv    
/home/username/opt/python-3.10.1/bin/virtualenv

You can then create a virtualenv using the full path like this:

[server]$ /home/username/opt/python-3.10.1/bin/virtualenv -p /home/username/opt/python-3.10.1/bin/python3 venv

See also

Did this article answer your questions?

Article last updated PST.

Still not finding what you're looking for?