Installation

FlatProt can be installed using uv (recommended) or pip. The package requires Python 3.11-3.13.

Quick Installation

Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then install FlatProt:

uvx tool install flatprot

Or for temporary usage:

uvx flatprot

Verify the installation:

flatprot --version

Using pip

pip install flatprot

Development Installation

For development work:

uv add flatprot

Required Dependencies

FlatProt has several external dependencies that need to be installed separately:

1. DSSP (Required for PDB Files)

DSSP is required for secondary structure assignment when working with PDB format files. FlatProt requires mkdssp version 4.4.0+.

Installation Options:

macOS (Homebrew):

brew install dssp

Ubuntu/Debian:

sudo apt-get install dssp

Conda/Mamba:

conda install conda-forge::dssp

Manual Installation: - Download from: DSSP Download Page - Follow platform-specific build instructions - Ensure the mkdssp executable is in your PATH

Verification:

mkdssp --version

2. FoldSeek (Required for Alignment Features)

FoldSeek is required for database alignment functionality in the align and split commands.

Installation Options:

Conda/Mamba (Recommended):

conda install bioconda::foldseek

Manual Installation: - Download from: FoldSeek GitHub - Follow platform-specific build instructions - Ensure the foldseek executable is in your PATH

Verification:

foldseek --version

3. Cairo (Optional - Required for PNG/PDF Output)

Cairo is required only for PNG and PDF output from the flatprot overlay command. SVG output works without Cairo.

macOS:

brew install cairo

Ubuntu/Debian:

sudo apt-get install libcairo2-dev pkg-config

Windows: Install Cairo binaries or use conda:

conda install cairo

Verification:

python -c "import drawsvg; print('Cairo available:', hasattr(drawsvg, '_cairo_available') and drawsvg._cairo_available)"

Complete Setup Workflow

Here's a complete setup workflow for different scenarios:

Basic Usage (CIF files only)

# Install FlatProt
uvx tool install flatprot

# Test with CIF file (no additional dependencies needed)
flatprot project structure.cif -o output.svg

Full Feature Usage

# Install FlatProt
uvx tool install flatprot

# Install dependencies
brew install dssp cairo  # macOS
conda install bioconda::foldseek conda-forge::dssp cairo  # Cross-platform

# Test full functionality
flatprot split structure.cif --regions "A:1-100" --show-database-alignment
flatprot overlay "structures/*.cif" -o overlay.png

Platform-Specific Notes

macOS:

  • Homebrew provides the most reliable installations
  • All dependencies available through brew
  • On newer M-series models, setting up Cairo requires manual adjustment to find the library path.

Linux:

  • Use package manager when possible
  • Conda/mamba provides consistent cross-distribution support

Windows:

  • Conda/mamba recommended for all dependencies
  • Manual installation may require additional build tools

Performance Optimization

For better performance, consider:

  1. Use CIF format when possible
  2. Pre-compute DSSP files for batch processing of PDB files

Next Steps

After installation, check out: