PackageCacheData

High-level management and querying of package caches

Beta - While in beta, expect both major and minor changes across minor releases.

Overview

The PackageCacheData class provides high-level access to conda’s package caches. Package caches store downloaded and extracted packages that can be linked into environments without re-downloading.

Constructor

from conda.api import PackageCacheData

cache = PackageCacheData(pkgs_dir="/opt/conda/pkgs")

pkgs_dir · str · required

The path to the package cache directory.

Methods

get

record = cache.get(package_ref)

Retrieve a specific package record from the cache by its PackageRef.

package_ref · PackageRef · required

A PackageRef instance representing the key for the PackageCacheRecord being sought.

default · any · default: "NULL"

The default value to return if the record does not exist. If not specified and no record exists, KeyError is raised.

return · PackageCacheRecord

The PackageCacheRecord for the requested package.

Example

from conda.api import PackageCacheData
from conda.models.records import PackageRef

cache = PackageCacheData("/opt/conda/pkgs")

try:
    record = cache.get(PackageRef("numpy", "1.21.0", "py39_0"))
    print(f"Found: {record.name} at {record.extracted_package_dir}")
except KeyError:
    print("Package not in cache")

# With a default value
record = cache.get(PackageRef("scipy", "1.7.0", "py39_0"), default=None)
if record:
    print(f"Found: {record.name}")
else:
    print("Package not in cache")

query

results = cache.query("numpy>=1.20")

Run a query against this specific package cache instance.

package_ref_or_match_spec · PackageRef or MatchSpec or str · required

Either an exact PackageRef to match against, or a MatchSpec query object. A string will be turned into a MatchSpec automatically.

return · tuple[PackageCacheRecord]

A tuple of PackageCacheRecord objects matching the query.

Example

from conda.api import PackageCacheData

cache = PackageCacheData("/opt/conda/pkgs")

# Query for numpy packages
results = cache.query("numpy>=1.20,<2.0")

for record in results:
    print(f"{record.name} {record.version} at {record.extracted_package_dir}")

query_all

results = PackageCacheData.query_all(
    "pandas",
    pkgs_dirs=["/opt/conda/pkgs", "/home/user/.conda/pkgs"]
)

Run a query against all package caches.

This is a static method, so call it on the class itself: PackageCacheData.query_all()

package_ref_or_match_spec · PackageRef or MatchSpec or str · required

Either an exact PackageRef to match against, or a MatchSpec query object. A string will be turned into a MatchSpec automatically.

pkgs_dirs · Iterable[str] or None · default: "None"

Iterable of package cache directory paths. If None, will fall back to context.pkgs_dirs.

return · tuple[PackageCacheRecord]

A tuple of PackageCacheRecord objects matching the query across all specified caches.

Example

from conda.api import PackageCacheData

# Query all default package caches
results = PackageCacheData.query_all("tensorflow")

for record in results:
    print(f"{record.name} {record.version} in {record.package_tarball_full_path}")

# Query specific caches
results = PackageCacheData.query_all(
    "python=3.11",
    pkgs_dirs=["/opt/conda/pkgs"]
)

iter_records

for record in cache.iter_records():
    print(record.name)

Iterates over all records contained in the package cache instance.

return · Iterable[PackageCacheRecord]

A generator over all PackageCacheRecord objects in the cache.

This is a generator that is exhausted on first use. If you need to iterate multiple times, store the results in a list.

Example

from conda.api import PackageCacheData

cache = PackageCacheData("/opt/conda/pkgs")

# List all cached packages
total_size = 0
for record in cache.iter_records():
    if hasattr(record, 'size'):
        total_size += record.size
    print(f"{record.name} {record.version}")

print(f"\nTotal cache size: {total_size / (1024**3):.2f} GB")

first_writable

cache = PackageCacheData.first_writable(pkgs_dirs=None)

Get an instance object for the first writable package cache.

This is a static method, so call it on the class itself: PackageCacheData.first_writable()

pkgs_dirs · Iterable[str] or None · default: "None"

Iterable of package cache directory paths. If None, will fall back to context.pkgs_dirs.

return · PackageCacheData

A PackageCacheData instance for the first writable package cache.

Example

from conda.api import PackageCacheData

# Get the first writable cache
cache = PackageCacheData.first_writable()
print(f"Writable cache location: {cache._internal.pkgs_dir}")
print(f"Is writable: {cache.is_writable}")

reload

cache = cache.reload()

Update the instance with new information. Backing information (i.e., contents of the pkgs_dir) is lazily loaded on first use by the other methods of this class.

You should only use this method if you are sure you have outdated data. In most cases, the cached information is sufficient and more efficient.

return · PackageCacheData

Returns self for method chaining.

Example

from conda.api import PackageCacheData

cache = PackageCacheData("/opt/conda/pkgs")

# Query some data
results = cache.query("numpy")

# Some external process may have modified the cache
# Force reload to get fresh data
cache = cache.reload()
results = cache.query("numpy")  # Now uses fresh data

Properties

is_writable

if cache.is_writable:
    print("Can write to this cache")

Indicates if the package cache location is writable or read-only.

type · bool

True if the cache is writable, False if read-only.

Example

from conda.api import PackageCacheData
from conda.base.context import context

# Check writability of all package caches
for pkgs_dir in context.pkgs_dirs:
    cache = PackageCacheData(pkgs_dir)
    status = "writable" if cache.is_writable else "read-only"
    print(f"{pkgs_dir}: {status}")

Complete Example

from conda.api import PackageCacheData
from conda.base.context import context

print("Package Cache Analysis\n" + "="*50)

# Find the first writable cache
writable_cache = PackageCacheData.first_writable()
print(f"\nFirst writable cache: {writable_cache._internal.pkgs_dir}")

# Analyze all package caches
print(f"\nAnalyzing {len(context.pkgs_dirs)} package caches...\n")

for pkgs_dir in context.pkgs_dirs:
    cache = PackageCacheData(pkgs_dir)
    
    print(f"Cache: {pkgs_dir}")
    print(f"  Writable: {cache.is_writable}")
    
    # Count packages in cache
    packages = list(cache.iter_records())
    print(f"  Packages: {len(packages)}")
    
    # Show some examples
    if packages:
        print("  Sample packages:")
        for record in packages[:3]:
            print(f"    - {record.name} {record.version}")
    print()

# Query for specific packages across all caches
print("\nSearching for numpy in all caches...")
results = PackageCacheData.query_all("numpy")
print(f"Found {len(results)} cached numpy packages:\n")

for record in results:
    print(f"  {record.name} {record.version} (build: {record.build})")
    print(f"    Location: {record.extracted_package_dir}")