Skip to content

Installation

Jump to bottom
Asaf Zorea edited this page Jan 25, 2026 · 1 revision

Installation Guide

Quick Install (PyPI)

The simplest way to install fastaccess is via pip:

pip install fastaccess

This will install the pure Python version, which works on all platforms with no dependencies.

Installing with C++ Backend (Recommended)

For better performance (up to 14x faster indexing), install from source to build the C++ backend:

Prerequisites

Required:

  • Python 3.8 or higher
  • C++17 compatible compiler
  • CMake 3.15 or higher
  • zlib development headers

Platform-specific requirements:

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y build-essential cmake zlib1g-dev python3-dev

macOS

# Install Xcode Command Line Tools
xcode-select --install

# Install CMake via Homebrew (if needed)
brew install cmake

Windows

Build from Source

Clone the repository and install in development mode:

git clone https://github.com/nuniz/FASTAccess.git
cd FASTAccess
pip install -e .

Or install development dependencies:

pip install -e ".[dev]"

This includes pytest, pytest-cov, and mypy for testing and type checking.

Verify C++ Backend

Check if the C++ backend was successfully built:

from fastaccess import using_cpp_backend

if using_cpp_backend():
    print("✓ C++ backend is active")
else:
    print("✗ Using pure Python backend")

Installation Methods Comparison

Method C++ Backend Use Case
pip install fastaccess ✗ No Quick install, no compilation needed
pip install -e . ✓ Yes Best performance, development
pip install -e ".[dev]" ✓ Yes Development with testing tools

Troubleshooting

C++ Backend Not Building

Issue: Installation completes but C++ backend is not available.

Check:

from fastaccess import using_cpp_backend
print(using_cpp_backend())  # Should print True

Common causes:

  1. Missing compiler

    • Linux: Install build-essential
    • macOS: Run xcode-select --install
    • Windows: Install Visual Studio with C++ tools

  2. CMake version too old

    cmake --version  # Should be 3.15+

    Update via package manager or download from cmake.org

  3. Missing zlib headers

    • Linux: sudo apt-get install zlib1g-dev
    • macOS: Usually included with Xcode
    • Windows: Usually included with Python

  4. Check build logs

    pip install -e . -v  # Verbose output

    Look for compilation errors in the output.

Import Errors

Issue: ModuleNotFoundError: No module named 'fastaccess'

Solution: Make sure you're in the correct environment:

pip list | grep fastaccess

If not listed, reinstall:

pip install fastaccess

Gzip Files Not Working

Issue: Error when opening .fa.gz files

Check: Python's gzip module (part of stdlib, should always work):

import gzip  # Should not raise error

Permission Errors on Cache Files

Issue: PermissionError when trying to save .fidx cache

Solution: Use a custom cache directory:

from fastaccess import FastaStore

# FASTA in read-only location
fa = FastaStore("/readonly/genome.fa", cache_dir="/tmp/fasta_cache")

Platform-Specific Notes

Linux

  • Most compatible platform for C++ backend
  • Use system package manager for dependencies
  • Works on all major distributions (Ubuntu, Debian, CentOS, Fedora)

macOS

  • Both Intel (x86_64) and Apple Silicon (arm64) supported
  • Xcode Command Line Tools required
  • C++ backend builds successfully on macOS 10.15+

Windows

  • Pure Python backend always works
  • C++ backend requires Visual Studio
  • Use PowerShell or Command Prompt (not Git Bash) for building

Virtual Environments

Recommended installation in a virtual environment:

# Using venv
python -m venv fastaccess-env
source fastaccess-env/bin/activate  # Linux/macOS
# or
fastaccess-env\Scripts\activate  # Windows

pip install fastaccess
# Using conda
conda create -n fastaccess python=3.10
conda activate fastaccess
pip install fastaccess

Upgrading

To upgrade to the latest version:

pip install --upgrade fastaccess

From source:

cd FASTAccess
git pull
pip install -e . --force-reinstall

Uninstalling

pip uninstall fastaccess

This will remove the package but not the cache files (.fidx files). To also remove cache files, delete them manually:

find /path/to/fasta/files -name "*.fidx" -delete

Clone this wiki locally