Skip to content

Managing your development environment

This guide explains how to manage Python packages in your QruiseOS JupyterLab environment. The base conda environment comes pre-installed with all required Qruise packages and is read-only to ensure stability. However, you can install additional packages for your own development work using the --user flag with pip.

Understanding the environment structure

The QruiseOS JupyterLab environment uses a layered approach:

  • Base environment: Contains all Qruise-managed packages (read-only)
  • User packages: Additional packages you install with --user flag (stored in ~/.local)

This separation ensures that:

  1. Core Qruise functionality remains stable and consistent
  2. You can experiment with additional packages without affecting the base environment
  3. You can easily clean up user-installed packages if needed

Installing packages

Installing from PyPI

To install a package from PyPI, use the --user flag:

pip install --user <package-name>

For example, to install the pandas-profiling package:

pip install --user pandas-profiling

Installing from a Git repository

You can also install packages directly from a Git repository:

pip install --user git+https://github.com/username/repository.git

Editable installs for development

If you're developing a package locally and want changes to be reflected immediately without reinstalling, use an editable install:

pip install --user -e <path-to-repo>

For example, if you've cloned a repository to your home directory:

git clone https://github.com/username/my-package.git ~/my-package
pip install --user -e ~/my-package

With an editable install, any changes you make to the source code in ~/my-package will be immediately available without needing to reinstall.

Installing a specific version

To install a specific version of a package:

pip install --user <package-name>==<version>

For example:

pip install --user numpy==1.24.0

Listing installed packages

To see all user-installed packages:

pip list --user

This shows only packages installed with the --user flag, not the base environment packages.

Uninstalling packages

Uninstalling a single package

To uninstall a specific user-installed package:

pip uninstall <package-name>

Uninstalling all user packages

If you need to clean up your environment and remove all user-installed packages, use the provided utility script:

qruise-uninstall-user-packages.sh

This script will:

  1. List all user-installed packages
  2. Ask for confirmation before proceeding
  3. Uninstall all packages that were installed with the --user flag

To skip the confirmation prompt, use the --yes flag:

qruise-uninstall-user-packages.sh --yes

Restoring example notebooks

The example notebooks in ~/qruise/examples demonstrate how to use QruiseOS features. If you've modified or deleted these notebooks and want to restore the original versions, use:

qruise-restore-examples.sh

This copies the original example notebooks from the read-only source to your ~/qruise/examples directory.

To completely replace the examples directory (removing any modifications or additional files you've added), use the --clean flag:

qruise-restore-examples.sh --clean

Using --clean

The --clean flag will delete all contents of ~/qruise/examples before restoring. Make sure to backup any custom notebooks or modifications you want to keep.

Best practices

  1. Always use --user: When installing packages, always include the --user flag to keep your installations separate from the base environment.
  2. Use virtual environments for projects: For larger development projects, consider creating a separate conda environment: 
conda create -n myproject python=3.11
conda activate myproject
  1. Document your dependencies: Keep track of packages you've installed by maintaining a requirements.txt.
  2. Clean up regularly: If your environment becomes cluttered, use qruise-uninstall-user-packages.sh to start fresh.
  3. Test editable installs carefully: When using editable installs, remember that changes to the source code take effect immediately, which can sometimes lead to unexpected behaviour if you're also running notebooks that import the package.