Squashing Your Python Environment

This guide walks you through creating a Python virtual environment using uv, compressing it into a SquashFS image using makesquash, and mounting it for use. Based on CSCS.

Tip

This tutorial should only be used by advanced users or under guidance of IT staff. 2026.02

1. Create a Virtual Environment with uv

Create a virtual environment (e.g., named venv):

# Create a relocatable virtual environment named 'venv'
uv venv venv --relocatable --link-mode=copy
# Activate it
source venv/bin/activate

Install your dependencies (example with requirements.txt):

uv pip install -r requirements.txt

2. Package the Environment with makesquash

Compress the virtual environment into a SquashFS file:

# Create a compressed SquashFS image of the virtual environment
mksquashfs venv venv.squashfs -no-recovery -noappend -Xcompression-level 3

This creates a compressed, read-only venv.squashfs file that contains the entire environment.

3. Mount the SquashFS File

To use the environment without unpacking it, mount it with squashfuse:

# Create a mount point (adjust path as needed)
mkdir -p /jetfs/home/$USER/venv
# Mount the SquashFS image (venv.squashfs) to that mount point
squashfuse venv.squashfs /jetfs/home/$USER/venv

You can now access and use the environment at /jetfs/home/$USER/venv.

Remember to use a path that you have access to.

Using the SHM for Performance (Optional)

The SHM (shared memory) filesystem can provide faster access times. When using slurm, the /dev/shm directory is available for temporary storage with the environment variable SHM_DIR pointing to it.

On Aurora or JET01, JET02 you can use /dev/shm/$USER for mounting:

# make sure to create a user directory in /dev/shm
mkdir -p /dev/shm/$USER/venv
# using slurm
mkdir -p $SHM_DIR/venv
# mount the SquashFS image to the SHM location
squashfuse venv.squashfs /dev/shm/$USER/venv
# or slurm
squashfuse venv.squashfs $SHM_DIR/venv

To activate the mounted environment:

# Activate the virtual environment from the mounted location
source /jetfs/home/$USER/venv/bin/activate
# or SHM
source /dev/shm/$USER/venv/bin/activate
# SLURM
source $SHM_DIR/venv/bin/activate

4. Unmount When Done

When you're finished:

fusermount -u /jetfs/home/$USER/venv

As a Slurm Job

On Jet one would want to use the SHM for better performance. Here is an example slurm script:

#!/bin/bash
#SBATCH --job-name=test_squash
#SBATCH --output=output.log
#SBATCH --error=error.log
#SBATCH --time=00:10:00
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=1
#SBATCH --mem=2G
#SBATCH --partition=general

# Load necessary modules
# Create a user directory
mkdir -p $SHM_DIR/venv
# Mount the SquashFS image to the SHM location
squashfuse $HOME/venv.squashfs $SHM_DIR/venv
# Activate the virtual environment from the mounted location
source $SHM_DIR/venv/bin/activate
# run your python script
python your_script.py
# Unmount when done
fusermount -u $SHM_DIR/venv

Slurm will clean up the SHM directory after the job ends, so no need to remove it manually.