conda-pack

Common errors

• conda: command not found

  cause `conda` executable is not in the system's PATH, or Conda/Miniconda is not installed.
  fix Install Miniconda or Anaconda, then ensure its `bin` directory (e.g., `~/miniconda3/bin`) is added to your system's PATH environment variable. Alternatively, use `micromamba`.

• CondaEnvironmentNotFoundError: Could not find conda environment: my_env

  cause The specified environment name (`-n my_env`) or prefix (`--prefix /path/to/env`) does not exist on the system where `conda-pack` is being run.
  fix Verify the environment name or path is correct using `conda env list`. If it's a new environment, create it first using `conda create -n my_env python=X.Y ...`.

• subprocess.CalledProcessError: Command '['conda', 'pack', '-n', 'my_env', '-o', 'my_env.tar.gz']' returned non-zero exit status 1.

  cause A generic error indicating `conda pack` failed. Often due to file existence (output file already exists) or permissions.
  fix If the output file already exists, add the `--force` flag to overwrite it. Check file permissions for the output directory and ensure you have write access. Check previous error messages in the console for more specific details from `conda pack`.

• ModuleNotFoundError: No module named 'conda_pack'

  cause `conda-pack` is not installed in the Python environment currently being used.
  fix Install the library using `pip install conda-pack` or `conda install conda-pack -c conda-forge` in the active environment.

Warnings

• breaking conda-pack itself now requires Python 3.9 or newer. Older versions of conda-pack (0.8.0 and below) supported older Python versions (e.g., 3.7). This applies to the Python interpreter running `conda-pack`, not the Python version inside the environment being packed.
  Fix: Ensure the Python environment where `conda-pack` is installed and executed is Python 3.9 or higher.
• gotcha conda-pack fundamentally relies on a functional `conda` or `micromamba` installation being available in the system's PATH where it is executed. It does not bundle `conda` itself.
  Fix: Install Miniconda/Anaconda or Micromamba and ensure the `conda` or `micromamba` executable is in your system's PATH before running `conda-pack`.
• gotcha While designed for relocatability, packed environments are generally not cross-platform or cross-architecture compatible. Packing an environment on Linux for deployment on Windows, or vice-versa, will usually fail. Similar issues can arise with different CPU architectures (e.g., x86_64 vs. ARM64).
  Fix: Pack environments on a system with the same operating system and architecture as the target deployment environment.
• gotcha Large environments with many packages can result in very large archive files. This can impact distribution time and storage requirements. Using compression options or ignoring specific components can help.
  Fix: Consider using `--compress-level` for better compression (e.g., `gzip:9`, `zstd:19`), `--compressor zstd` (available since 0.8.1) for faster/better compression, or `--ignore-pip` to exclude pip-installed packages if they are not strictly necessary or can be reinstalled on target.

Install

• pip install conda-pack Via pip
• conda install conda-pack -c conda-forge Via Conda-forge

Imports

• pack

  from conda_pack import pack

  Primary function for programmatic environment packing.

Quickstart

This quickstart demonstrates how to pack an existing conda environment into a tar.gz archive using the `conda pack` command-line tool. It first ensures a sample environment exists, then packs it to a specified output file. The `--force` flag overwrites the output if it already exists.

import os
import subprocess

# Create a dummy environment for demonstration if it doesn't exist
env_name = 'my_packed_env'
if subprocess.run(['conda', 'env', 'list'], capture_output=True, text=True).stdout.find(env_name + ' ') == -1:
    print(f"Creating dummy conda environment '{env_name}'...")
    subprocess.run(['conda', 'create', '-n', env_name, 'python=3.9', 'numpy', '-y'], check=True)

output_filename = f'{env_name}.tar.gz'

# Pack the environment using the command line tool
print(f"Packing environment '{env_name}' to '{output_filename}'...")
subprocess.run(['conda', 'pack', '-n', env_name, '-o', output_filename, '--force'], check=True)

print(f"Environment packed to {output_filename}")

# To unpack (demonstrative, not part of conda-pack library itself)
# print(f"Unpacking {output_filename} to ./unpacked_env")
# os.makedirs('./unpacked_env', exist_ok=True)
# subprocess.run(['tar', '-xzf', output_filename, '-C', './unpacked_env'], check=True)

# To use the Python API directly:
# from conda_pack import pack
# pack(name=env_name, output=output_filename, force=True)