Installation¶

This guide covers different ways to install the py-cid package, from simple usage to full development setup.

Quick Install¶

For basic usage, install the package directly from PyPI:

pip install py-cid

This installs the latest stable version with all required dependencies.

Installation Methods¶

From PyPI (Recommended)¶

For production use or when you want the latest stable release:

pip install py-cid

From Source¶

If you want to install from the source code:

# Clone the repository
git clone https://github.com/ipld/py-cid.git
cd py-cid

# Install in normal mode
pip install .

Development Installation¶

For development work, you’ll want to install the package in editable mode so that changes to the source code are immediately reflected. It’s recommended to use a virtual environment for development:

Development Install¶

Create a virtual environment and install the package in development mode with all development dependencies:

# Create a virtual environment
python3 -m venv ./venv

# Activate the virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable/development mode with dev dependencies
python3 -m pip install -e ".[dev]"

# Install pre-commit hooks for code quality
pre-commit install

Or use the provided Makefile:

make install-dev

Using the Makefile¶

The project includes a Makefile with convenient commands:

# Show all available commands
make help

# Install in development mode
make install-dev

# Install in normal mode
make install

# Run tests
make test

# Run linting
make lint

# Build distribution packages
make dist

# Generate documentation
make docs

Troubleshooting¶

Common Issues¶

ImportError: No module named ‘multihash’

Make sure you have installed all dependencies: pip install -e “.[dev]”

Permission Errors

Use a virtual environment to avoid permission issues:

python3 -m venv ./venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
python3 -m pip install -e ".[dev]"

Build Errors

Ensure you have the latest pip and setuptools:

pip install --upgrade pip setuptools wheel

Virtual Environment¶

It’s recommended to use a virtual environment for development to isolate your project dependencies from your system Python installation:

# Create a virtual environment
python3 -m venv ./venv

# Activate it (Linux/Mac)
source venv/bin/activate

# Activate it (Windows)
venv\Scripts\activate

# Install in development mode with all dependencies
python3 -m pip install -e ".[dev]"

# Install pre-commit hooks for code quality
pre-commit install

This setup provides: - Isolated dependencies from your system Python - All development tools (pytest, mypy, ruff, pre-commit, etc.) - Automatic code quality checks on commit - Editable installation for immediate code changes