Installation

This guide covers everything you need to know to install Colorium and get it running on your system.

System Requirements

Before installing, ensure your system meets these requirements:

Python 3.8 or higher
pip (Python package installer)
Internet connection (for downloading the package)

Installing from PyPI

The simplest way to install Colorium is from PyPI:

pip install colorium

This installs the latest stable version with all core features.

Install with Extra Features

For development work with additional tooling:

pip install "colorium[dev]"

This installs Colorium along with development tools including:

pytest for testing
black for code formatting
flake8 for linting
mypy for type checking

Installing from Source

To install the latest development version directly from GitHub:

git clone https://github.com/inject3r/colorium.git
cd colorium
pip install -e .

The -e flag installs in editable mode, allowing you to modify the source code and see changes immediately.

Verifying Installation

After installation, verify that Colorium is working correctly:

# Verify import
python -c "from colorium import Color; print('Colorium is installed!')"

# Create a simple color
python -c "from colorium import Color; red = Color(255, 0, 0); print(red.to_hex_string())"

Expected output:

Colorium is installed!
#FF0000

Installation Details

What Gets Installed

Colorium has zero external dependencies, so only the library itself is installed:

colorium/
├── color.py          # Core Color class
├── core.py           # Parser and factory functions
├── converters.py     # Color space conversions
├── constants.py      # Named color constants
├── constants_colors.py # Pre-defined color constants
├── filters.py        # Color filters
├── filter_base.py    # Base filter classes
└── utils.py          # Utility functions

Installation Locations

The installation location depends on your Python environment:

Global install: /usr/lib/python3.x/site-packages/colorium/
User install: ~/.local/lib/python3.x/site-packages/colorium/
Virtual environment: venv/lib/python3.x/site-packages/colorium/

Upgrading

To upgrade Colorium to the latest version:

pip install --upgrade colorium

To upgrade to a specific version:

pip install colorium==1.0.0

Uninstalling

To remove Colorium completely:

pip uninstall colorium

Installation Issues

Common Problems

Issue	Solution
Permission denied	Use `pip install --user colorium` or use a virtual environment
pip not found	Install pip: `python -m ensurepip --default-pip`
Python version too old	Upgrade to Python 3.8 or higher
Network timeout	Use `pip install --timeout 100 colorium`
SSL certificate error	Use `pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org colorium`

Virtual Environment Setup

For isolated development:

# Create virtual environment
python -m venv venv

# Activate on Linux/Mac
source venv/bin/activate

# Activate on Windows
venv\Scripts\activate

# Install Colorium
pip install colorium

Next Steps

Now that you have Colorium installed, continue with:

Quick Start — Build your first color application
Usage Examples — Real-world examples
Core Concepts — Learn about color spaces and operations

Next: Quick Start →