Configuration

Credentials

NCBI searches work without an API key. Set NCBI_API_KEY for the higher E-Utilities rate limit and NCBI_EMAIL for your contact address. PYNCBI_API_KEY and PYNCBI_EMAIL are supported aliases. Keys are redacted from PyNCBI logs and error URLs. Never put real keys in issue reports, notebooks committed to Git, or MCP configuration examples.

Sessions

import PyNCBI

with PyNCBI.Session(cache_dir="./task-cache", max_download_mb=500) as session:
    result = session.load_expression("GSE152418")
    print(session.metrics())

Sessions own their configuration, client, caches and telemetry. Their generated typing stubs expose the same signatures as the module-level functions. An explicit function budget wins over the session default. The budget resets for each top-level operation.

Transfer limits

PYNCBI_MAX_DOWNLOAD_MB sets the default budget (2048 MB). 0 disables it; negative or non-finite values are rejected when starting a transfer. An explicit max_download_mb= or CLI --max-download-mb overrides the default where exposed.

A download operation shares its limit across nested calls and parallel workers, including metadata bodies requested within that operation. Cached responses do not consume network bytes. Both declared sizes and actual delivered chunks are checked. A missing HEAD size cannot bypass the byte limit. A rejected transfer may already have read an in-flight chunk, and concurrent requests may already be receiving data. The ceiling bounds accepted response/file data; it is not an exact cap on network traffic or billing. Direct client calls use a per-response default budget.

Preflight size checks use the same operation budget as the transfer, including bytes already received. When an explicit client owns a configuration, its default applies instead of a competing global default. max_download_mb= still overrides that default for a top-level operation.

The count is bytes delivered by requests after HTTP content decoding, before file/archive expansion. It is not a ceiling on RAM usage, uncompressed archive contents, exported CSV size, or the total transferred by a session over its lifetime. Budget exhaustion can leave completed files or a partial staging file; inspect the reported paths before retrying.

Raw file downloads check free disk space before and during writes. check_disk_space=False (or --no-disk-check where exposed) skips those checks. Archive expansion and table export can require substantially more space than the download. Review pyncbi download --dry-run before large transfers; totals are incomplete when servers omit sizes.

Other environment variables

Variable	Meaning
`PYNCBI_CACHE_DIR` / `PYNCBI_CACHE_FOLDER`	Cache root (default `~/.cache/PyNCBI`; respects `XDG_CACHE_HOME`)
`PYNCBI_REQUEST_TIMEOUT`	Request timeout in seconds (default 30)
`PYNCBI_HTTP_CACHE_TTL`	In-memory metadata response lifetime in seconds (default 300; 0 disables)
`PYNCBI_AUDIT_LOG`	Append-only JSONL request audit path
`PYNCBI_AGENT_MODE`	Suppress colors and progress (`1` enables, `0` disables)
`NO_COLOR`	Disable terminal colors

Cache directories are created when used, not on package import or --help / --version.