---
title: Installation
---

## Availability and requirements

The `colorspace` package is available via the
[Python Package index (PyPI)](https://pypi.org/project/colorspace/) or via 
[GitHub](https://github.com/retostauffer/python-colorspace).

It has the following requirements.

* Python 3.8 or greater (GitHub Actions test for versions {{PYTEST_VERSIONS}})
* [`numpy`](https://pypi.org/project/numpy/>)
* [`matplotlib`](https://pypi.org/project/matplotlib/>) (optional; used for visualization)
* [`imageio`](https://pypi.org/project/imageio/>) (optional; only used by
    [`cvd_image`](/man/colorspace.cvd_image.cvd_image.qmd))
* [`pandas`](https://pandas.pydata.org/) (optional; used by [`dataset`](/man/colorspace.datasets.dataset.qmd))

Additionally, Python's [`tkinter`](https://docs.python.org/3/library/tkinter.html) interface
to Tcl/Tk is leveraged (optional, only used by the [interactive palette app](articles/choose_palette.qmd)).
This is typically installed along with the base Python system but might not be available, e.g.,
on certain Linux distributions. If so, a `RuntimeError` is raised when invoking the app with
some comments for [installation](https://tkdocs.com/tutorial/install.html).


## Installation instructions

The latest release version can be installed from [PyPI](https://pypi.org/project/colorspace/)
using:

```
pip install colorspace
```

Similarly, the optional requirements (see above) can be installed using:

```
pip install imageio matplotlib pandas
```

The latest development version (GitHub head branch) can be installed using:

```
pip install setuptools # Ensure setuptools installed
pip install git+https://github.com/retostauffer/python-colorspace
```

Alternatively, clone the git repository and install the package from there:

```
git clone https://github.com/retostauffer/python-colorspace.git
cd python-colorspace && pip install setuptools && pip install .
```

To employ a Python virtual environment, say `my_venv`, you can
initialize and activate it prior to the commands above using:

```
virtualenv my_venv && source my_venv/bin/activate
```


## Bug reports and feature requests

Please use the [GitHub issues](https://github.com/retostauffer/python-colorspace/issues)
to report bugs and feature requests. See the [community guidelines](community.qmd)
for details.

Pull requests or also possible in the GitHub repository. If feasible, it is
appreciated when the package's tests (see below) are run prior to posting a
pull request.


## Test and development

The following sections are intended for developers, rather than regular users,
and gives some insights on how to run automated tests, create
coverage reports, test examples, and render the documentation.

### Testing

To run the automated tests with minimal requirements, we suggest
to clone the repository, set up a virtual environment with the
required packages, and then run the test using `pytest`.

```
# Cloning current main branch
git clone https://github.com/retostauffer/python-colorspace.git

# Changing directory
cd python-colorspace

# Setting up and activating virtual environment
virtualenv my_venv
source my_venv/bin/activate

# Installing pytest and additional packages as well
# as pytest and setuptools (to ensure both are installed)
pip install -r requirements.txt pytest setuptools

# Installing Python colorspace (from current main branch)
pip install -e .

# Run tests
pytest
```

For those using the GNU make utility, the package comes with
a `Makefile` which includes rules for running hard (minimal dependencies)
and extended (additional dependencies) tests. 

```
# Cloning current main branch
git clone https://github.com/retostauffer/python-colorspace.git

# Changing directory
cd python-colorspace

# Creating a fresh `hardvenv` virtual environment and running hard tests only
make hardtest

# Setting up virtual environment with all dependencies for full
# tests as well as for creating the documentation, calculating
# coverage etc., activating venv, installing Python colorspace, and
# running full tests (hard and extended tests)
make venv && source venv/bin/activate && make install && make test
```

### Development

For the developers out there, the `Makefile` provides additional
rules for creating/updating the man pages, creating the coverage report,
testing the docstring examples, and rendering the documentation. Note
that the latter two require [`quarto`](https://quarto.org) to be installed.

```
# Cloning current main branch
git clone https://github.com/retostauffer/python-colorspace.git

# Changing directory
cd python-colorspace

# Setting up virtualenv, installing colorspace (main)
make venv && make install

# Activate venv
source venv/bin/activate

# Running tests: Runs 'hard tests' (minimal requirements) first,
# followed by extended tests (with additional requirements)
make test

# Create coverage report; tries to open report in firefox
make cov

# Testing docstring examples; requires pyp2qmd and quarto
make examples

# Building documentation; requires pyp2qmd and quarto
make render
```
