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.
- Log into your server via SSH.
- Install a custom version of Python 3, which also contains pip3.
- 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.
- Run the following command to upgrade pip3.
[server]$ python3 -m pip install --upgrade pip
- 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 - 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.
- 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
- Navigate to your site's directory, where you'll create the new virtual environment:
[server]$ cd ~/example.com
- Update your .bash_profile
[server]$ . ~/.bash_profile
- 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
(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