Frequently Asked Questions / Troubleshooting¶

Concepts¶

Why does each solution get its own environment?¶

Album creates a dedicated micromamba environment for every installed solution so that routines with conflicting dependencies (different Python, CUDA, PyTorch, R, … versions) can coexist on the same machine. The host Album environment only runs the lightweight controller; your solution runs in a clean, isolated environment that exactly matches its specification. This is the same property that lets a single workflow combine several segmentation backends with mutually incompatible stacks (see case-studies, scenario B).

How is Album different from a package manager / workflow engine / container?¶

Album is not a replacement for any of them — it composes with them:

Package managers (conda, pip) distribute libraries; Album distributes executable routines, including their environment, lifecycle hooks (install / run / test), arguments, and citation metadata.
Workflow engines (Snakemake, Nextflow, Galaxy) orchestrate multi-step analyses; Album makes individual steps easier to package, execute, and validate independently. An Album solution can be reused as a workflow step.
Containers are great for long-term portability of mature artifacts. Album solutions are lighter to build and iterate on during development; the album-docker plugin lets you containerize a solution when it has stabilised.

Can I use Album with an LLM agent?¶

Yes, via Album MCP. The agent is constrained to the solutions actually present in your catalogs — it discovers, installs, and runs them through typed tool calls instead of free-form shell commands.

Album installation¶

The installation wizard appears to not have started (Windows)¶

The wizard runs in the background and may take several minutes on some systems to download and install all components.

The installation wizard fails due to network issues (all OS)¶

The wizard needs network access to download micromamba and to install packages from conda-forge. If firewall or proxy settings block these downloads, adjust your network / proxy settings. Ask your IT department for help if you are unsure about your institutional rules.

MacOS Gatekeeper warning (“Apple can’t check app for malicious software”)¶

Click Done, open System Settings → Privacy & Security, scroll down to Security, click Open Anyway next to the message about the installation wizard and confirm that you want to open it. This only needs to be done once. If you work in an institution: Ask your IT department for help if you are unsure about your institutional rules.

Linux: “Permission denied” when running the installer¶

The downloaded file must be made executable first:

chmod +x ./album_installer

How do I uninstall Album?¶

Delete the .album directory in your home directory and the Album shortcuts. This removes micromamba, all Album environments and all installed solutions. The steps for each operating system are in Uninstallation.

`micromamba` command not found¶

If you installed Album with the installation wizard, activate the Album environment as shown in Using Album on the command line.

If you installed micromamba manually, make sure shell initialisation has been run:

micromamba shell init -s bash -r ~/micromamba

Replace bash with your shell (zsh, fish, powershell) and restart your terminal. See the micromamba documentation for details.

Individual Album solution installation¶

Solution installation fails due to missing `git` command (all OS)¶

Album requires git for catalog management and some solution installations. If you installed Album via micromamba create -n album album -c conda-forge, git is included automatically. If you installed via pip, you must install git separately — see for instance this guide.

Tensorboard triggers antivirus alerts (Windows)¶

Some solutions that use tensorboard (e.g. deep-learning workflows) may trigger the antivirus scanner. If this happens, ask your IT department for help.

Running Album in parallel¶

Running several album processes at the same time¶

Several album processes, or scripts using the Python API, can use the same Album base directory at the same time - for example from two terminals, or the jobs of a batch run on an HPC cluster. A process that installs, uninstalls or downloads a solution waits while another process works on the same solution.

Advanced configuration¶

Using your own micromamba installation¶

By default Album downloads and manages its own micromamba binary. If you already have micromamba installed on your system and want Album to use it instead, set the ENVIRONMENT_DEBUGGING_MICROMAMBA_PATH environment variable to point to your existing micromamba executable:

export ENVIRONMENT_DEBUGGING_MICROMAMBA_PATH=/path/to/your/micromamba

On Windows (PowerShell):

$Env:ENVIRONMENT_DEBUGGING_MICROMAMBA_PATH = "C:\path\to\micromamba.exe"

This is useful when working behind a firewall that prevents Album from downloading micromamba, when you need a specific micromamba version, or for development and debugging purposes.