Install & Compatibility
Where this runs
tested against v0.13.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 204.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 14.3s · import 0.000s · 197MB
212MB installed
● package 212MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RefgenieClient
✓ from refgenie import RefgenieClient
✗ from refgenie import RefgenieClient
Initialize a RefgenieClient, list available genomes, and demonstrate how to interact with assets. This example includes a setup for a dummy config file to make it runnable even if Refgenie hasn't been initialized via the CLI, though actual asset retrieval requires prior `refgenie pull` or `refgenie build` commands.
import refgenie
import os
# Initialize RefgenieClient. It will look for ~/.refgenie/refgenie.yaml by default.
# For a temporary or custom config, provide the path.
# If no config is found at the default path, an empty client is initialized.
# For this example, we'll try to use a default or an empty one.
# Create a dummy refgenie.yaml for demonstration if it doesn't exist
config_path = os.path.expanduser("~/.refgenie/refgenie.yaml")
if not os.path.exists(os.path.dirname(config_path)):
os.makedirs(os.path.dirname(config_path))
if not os.path.exists(config_path):
with open(config_path, 'w') as f:
f.write("refgenie:\n genome_config_version: 0.2\n genomes: {}\n")
rg = refgenie.RefgenieClient(config_file=config_path)
print(f"Refgenie client initialized. Config file: {rg.config_file}")
# List available genomes (will be empty if no assets are pulled)
genomes = rg.list_genomes()
print(f"Available genomes: {list(genomes.keys())}")
# Example: trying to get an asset (will likely fail if not pulled/built)
# To make this runnable without pre-pulled assets, we'll skip direct asset retrieval
# Try to get a non-existent asset to show expected behavior without erroring
try:
# This assumes 'human_genome' is a valid genome and 'fasta' is an asset for it
# For a real scenario, you would run `refgenie pull human_genome/fasta` first
# or build your own assets.
# asset_path = rg.get_asset("human_genome/fasta")
# print(f"Path to human_genome fasta: {asset_path}")
print("To get an asset, first ensure it's pulled or built locally.")
print("Example: 'refgenie pull hg38/fasta' from command line.")
except Exception as e:
print(f"Could not retrieve asset (expected if not pulled): {e}")
# Clean up dummy config for demonstration
# os.remove(config_path)
# os.rmdir(os.path.dirname(config_path)) # Only if directory is empty
refgenie --version
Debug
Known issues
breakingRefgenie config file schema has undergone breaking changes across major versions (e.g., 0.10.0). Using an older `refgenie.yaml` with a newer version of the library can lead to errors.fixRun `refgenie config upgrade` from the command line after updating the `refgenie` library to ensure your configuration file is compatible with the installed version.
affects: prior to 0.10.0, and other minor upgrades
breakingThe primary CLI command for adding new assets changed from `refgenie add` to `refgenie build` in version 0.9.0. Using the old command with newer versions will result in a 'command not found' error.fixReplace all instances of `refgenie add` with `refgenie build` in scripts and commands.
affects: 0.9.0 and later
gotchaThe `RefgenieClient` constructor will by default attempt to load `~/.refgenie/refgenie.yaml`. If this file doesn't exist, it will initialize an empty client without raising an error. This can lead to unexpected behavior if you expect an error for a missing configuration or an automatically populated client.fixAlways explicitly check `rg.list_genomes()` or `rg.config_file` after initialization to confirm the client has loaded the expected configuration. For custom paths, provide `config_file='/path/to/my/refgenie.yaml'`.
affects: all
Upgrade
Version history
0.13.0latest on PyPI · released Feb 25, 2026
Audit
Dependencies
genomelakerequiredCore dependency for genome data management.
yacmanrequiredConfiguration and YAML management utility.
richoptionalOptional dependency for enhanced CLI output.
dockeroptionalOptional dependency for containerized build and management features.