Installation and dependencies

The current cdskit source requires Python 3.10 or newer; core CI tests Python 3.10–3.14 on the supported OS matrix. See pyproject.toml for package requirements and TESTING.md for developer environments. This page describes current master; older packages may have different options.

GitHub installation

Create and activate a virtual environment, then install from GitHub. CDSKIT is not published on PyPI, so pip install cdskit or pip install 'cdskit[ml]' without a repository URL is not a supported installation command.

python -m venv .venv
# POSIX shells; on Windows use .venv\Scripts\Activate.ps1 in PowerShell.
source .venv/bin/activate
python -m pip install --upgrade 'cdskit @ git+https://github.com/kfuku52/cdskit.git'
cdskit --version
cdskit --help

Using python -m pip helps ensure that cdskit is installed into the same Python environment you intend to run.

Bioconda

Use Bioconda's channel order and strict priority:

conda create -n cdskit -c conda-forge -c bioconda --strict-channel-priority \
  cdskit 'python>=3.10' 'biopython>=1.80' 'numpy>=1.23' 'matplotlib-base>=3.6' 'filelock>=3.12'
conda activate cdskit
cdskit --version

As checked on 2026-09-22, the Bioconda 0.31.0 recipe still declares Python >=3.8 and Biopython >=1.77, leaves NumPy unbounded, and omits Matplotlib and filelock. The explicit requirements above are a workaround for that packaging mismatch, not extra CDSKIT features. They can be removed once the published recipe's runtime dependencies match upstream metadata. GitHub source installation already resolves the required base dependencies. Tagged releases also need a downstream recipe update and successful build before appearing in Bioconda; publication is not immediate. The recipe still lists BSD-3-Clause, whereas current source and CDSKIT-trained model weights are MIT. Check the installed version: stats --mode alignment requires CDSKIT >=0.31.0, the default ESM2 localization model requires >=0.30.3, and the optional integrated CNN requires

=0.29.0. Recipe inspection alone does not verify a published binary or solve.

Bioconda supports Linux and macOS. For native Windows, use the GitHub pip installation; the project tests Windows separately from Bioconda packaging.

Base dependencies

The GitHub pip installation includes:

• Biopython >=1.80 for sequence and GenBank I/O;
• NumPy >=1.23 for numerical operations;
• Matplotlib >=3.6 for cdskit plot;
• filelock >=3.12 for model-cache and other cross-process locks.

These dependencies are installed automatically.

Optional machine-learning dependencies

Lightweight centroid JSON localization models need only the base installation. The full neural training and prediction toolset uses the ml extra:

python -m pip install --upgrade 'cdskit[ml] @ git+https://github.com/kfuku52/cdskit.git'

This extra includes torch >=2.2, scikit-learn >=1.4, transformers >=4.40, and PyYAML >=6. PyYAML supports the staged training configuration format. Transformers is already included; installing only torch and scikit-learn is not equivalent to installing the full extra. ESM models also need their encoder files, downloaded from a pinned revision or supplied locally.

The ml-cpu extra selects CPU-only PyTorch on Linux when installed through uv with this repository's source configuration, as in the development profiles. Pip does not read that uv index configuration: installing .[ml-cpu] with pip alone does not select CPU-only wheels. Pip users must select the appropriate PyTorch index separately.

GPU support is optional. Published cdskit localization models run on CPU; CUDA or Apple MPS mainly helps when retraining neural models.

Default ESM2 localization model runtime

The default esm2-localization-v1 alias uses ESM2 650M and a CDSKIT-trained Light Attention head. Install the ml extra above. Both the head and encoder are downloaded on first use; the CDSKIT model cache and Hugging Face encoder cache are separate. CPU inference is supported, but this model is more costly than the compact CNN because the encoder runs for every sequence. See the model guide for offline cache setup and measured runtime conditions.

Integrated ten-label model runtime

The integrated v1 model requires CDSKIT >=0.29.0 and PyTorch. For inference, install:

python -m pip install --upgrade 'cdskit @ git+https://github.com/kfuku52/cdskit.git' 'torch>=2.2'

This checkpoint needs neither scikit-learn nor Transformers and does not download an ESM encoder. It uses safe loading with the default --allow_unsafe_model no. The installed 0.29.0 wheel was verified on Python 3.12 and PyTorch 2.14.0 without those optional packages: labels matched the evaluation on 1,717 HPA proteins and 115 additional peroxisome-positive proteins. This records a verified runtime, not validation of every PyTorch version allowed by package metadata.

Pretrained targeting5 runtime

The published targeting5 and targeting5-perox-deeploc21-et-v1 artifacts contain scikit-learn 1.5.2 estimators. Current CDSKIT handles their short Cython module names and the stateless binomial reconstructor removed in scikit-learn 1.9.0. Both published models were compared against 1.5.2 on Linux ARM64: 384 output rows across DNA/protein inputs and all organism groups matched. General cross-version loading of custom sklearn estimators remains outside this validation; see sklearn's model persistence guidance.

For these published models, install the ML extra in a Python 3.12 environment:

python3.12 -m venv .venv-targeting5
source .venv-targeting5/bin/activate
python -m pip install \
  'cdskit[ml] @ git+https://github.com/kfuku52/cdskit.git'

On Windows, use py -3.12 -m venv .venv-targeting5 and activate .venv-targeting5\Scripts\Activate.ps1 in PowerShell. The 1.9.0 compatibility comparison used Python 3.12.14, torch 2.13.0 and NumPy 1.26.4 on Linux ARM64; it does not validate every platform or dependency combination. sklearn's version warnings remain visible. For an exact training-version reference, install scikit-learn==1.5.2 in a separate environment; this is a reproduction choice, not a library dependency bound. Record dependencies when training custom sklearn models.

Parallel work and resource limits

Only commands that advertise --threads support it. --threads 1 is the default; positive values request that many workers and 0 detects CPUs up to the safety limit (64 by default). Explicit values above the limit are rejected. Set CDSKIT_MAX_THREADS to change the ceiling. Small workloads may still run serially, so this option does not guarantee a particular number of active threads.

CPU-bound record operations can use processes instead of threads. Their default crossover is 16,000,000 input residues, configurable with CDSKIT_PROCESS_PARALLEL_MIN_RESIDUES. Vectorized translation runs serially. label and other metadata-only commands have no --threads option.

Troubleshooting

• If cdskit is not found, confirm that the environment's scripts directory is on PATH, or run the executable from the same activated virtual environment.
• Use cdskit COMMAND --help to check current option names and defaults.
• Boolean options accept yes/no, true/false, on/off, and 1/0.
• Legacy model compatibility and offline cache setup are documented in the prediction guide.

Output file permissions

Named sequence/report outputs are replaced without a confirmation prompt; missing parent directories are created. Input/output and output/output path collisions are rejected. Shell redirection (> file) is handled by the shell and does not provide CDSKIT's atomic replacement or collision checks. Staged training runs have separate resume rules.

Atomic replacement preserves an existing file's POSIX permission bits. Newly created outputs are private (0600); explicitly change their permissions when sharing them. File ownership and ACLs are not copied. Windows retains its native permission behavior. Multiple outputs are staged before replacement and rolled back if a commit fails.