How to use Pipenv to create virtual environments

Pipenv is a package and dependency manager for Python projects. It harnesses the power of different existing tools, bringing their functionalities together:

• pip for Python package management
• pyenv for Python version management
• Virtualenv for creating different virtual Python environments
• Pipfile for managing project dependencies

Pipenv is preinstalled on all of Scaleway’s AI Docker images for GPU Instances. Launching one of these Docker images puts you in an activated Pipenv virtual environment, with all your favorite packages and tools preinstalled. You can also use Pipenv to create your own virtual environments, if you wish to go beyond the preinstalled Python environments already provided with the various Docker images.

Before you start

To complete the actions presented below, you must have:

• A Scaleway account logged into the console
• Owner status or IAM permissions allowing you to perform actions in the intended Organization
• A GPU Instance
• An SSH key added to your account

Accessing the Pipenv virtual environment

See our dedicated documentation on how to access the Pipenv virtual environment from your Scaleway GPU Instance.

Managing packages with Pipenv

You can view packages, install/uninstall packages and update packages with a few simple pipenv commands:

1. Enter the following command to see all the packages and dependencies installed in this environment, and their versions:

   pipenv graph

2. Enter the following command to install a new package:

   pipenv install <package>

   Tip

   To install a specific version of a package, use the command pipenv install <package>~=1.2

3. Enter the following command to uninstall a package:

   pipenv uninstall <package>

4. Enter the following command to update a package:

   pipenv update <package>

   Tip

   To update all packages, simply run pipenv update

   Important

   Be aware that installing and updating packages may provoke conflicts with the existing virtual environment installation.

Understanding Pipfiles

Every Pipenv virtual environment has its own Pipfile. The Pipfile details the dependencies of the project, taking the place of the typical requirements.txt file. When you create a Pipenv environment, a Pipfile is automatically generated.

1. From within the Docker container, in the ~/ai directory, type ls to list all files in this directory

   The output should be similar to the following:

   Pipfile  Pipfile.lock
   

2. Enter the command cat Pipfile to view the contents of Pipfile. The following information will help you understand the output:

   • source specifies the sources where available packages are added/installed from
   • packages lists the packages required for the project (production and development environments)
   • dev-packages lists the packages required for the project (development environments only)
   • requires specifies the required python version for the project

   Any packages that you explicitly install with the command pipenv install <package> will automatically be added to the Pipfile. If you push your project to a Git repository, other users who clone it will be able to install all dependencies, based on the Pipfile, with the command pipenv install.

3. Enter the command cat Pipfile.lock to view the contents of Pipfile.lock.

   This file specifies which specific versions of the packages in the Pipfile should be used. This prevents packages which depend on each other being automatically upgraded, which could break your project dependency tree.

Creating your own virtual environments

1. Ensure you have connected to your GPU Instance via SSH and then launched a Scaleway AI Docker container.

   You are now in the ~/ai directory of the Docker container, with the virtual environment activated.

2. Type exit to exit the virtual environment.

3. Type cd ~ to leave the ~/ai directory and go to the home directory.

4. Create a new project directory for your new virtual environment, and navigate into it. Replace my-proj with the desired name for your project.

   mkdir my-proj && cd my-proj

   Tip

   To avoid losing your virtual environment upon exiting the container, make sure you create this folder in a directory that is mapped to one of your GPU Instance’s local volumes

5. Create a new virtual environment and generate a Pipfile:

   pipenv install

6. Activate the virtual environment:

   pipenv shell

   Your command prompt should now be similar to (my-proj) jovyan@442a38468c20:~/my-proj, showing that you are in the activated my-proj Pipenv virtual environment.

Further help

See the official Pipenv documentation for further help with Pipenv.