Installation

Pooltool is available on Linux, Mac, and Windows for the following Python versions:

Using pip

Pooltool is hosted on the Python Package Index (PyPI) and can be installed with pip.

LinuxMacOSWindows

pip install pooltool-billiards --extra-index-url https://archive.panda3d.org/

(Providing the Panda3D archive is required until Panda3D v1.11 is released)

From source

If you want to develop for pooltool, have access to the most up-to-date version of the codebase, or modify the code to your liking, this is for you.

[Click to expand/collapse]

A small note. If you don’t have the ability to create isolated python environments, I would recommend installing conda (here) so you can isolate pooltool from your other business.

1. Grab a copy of the codebase.

cd <A_DIRECTORY_YOU_LIKE>
git clone https://github.com/ekiefl/pooltool.git
cd pooltool

2. Create a new python environment that uses Python 3.13.0.

If you have conda, just run this:

conda env create -f environment.yml
conda activate pooltool-dev

Regardless of how you managed your python environment, please verify you’re running 3.13.0

$ python
Python 3.13.0 | packaged by Anaconda, Inc. | (main, Oct  7 2024, 16:40:03) [Clang 14.0.6 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> exit()

3. Install poetry, a popular python package/environment manager.

If you created your environment with conda (e.g. conda env create -f environment.yml), poetry is already part of your pooltool-dev environment.

Otherwise, install with

pip install "poetry>=1.8.3"

Verify your installation:

$ poetry --version
Poetry (version 1.8.3)

4. Install pooltool.

poetry install --with=dev,docs
pip install -e .

# Intend to contribute? Install the pre-commit hooks.
# This ensures your code is automatically formatted
# to pooltool's code standards before each commit.
pre-commit install

5. Test out your installation:

run-pooltool

The game window should appear (escape key to exit).

Test

Test your installation by printing the version:

python -c "import pooltool; print(pooltool.__version__)"

If installed from source, output should be 0.0.0.

Next, check out The Interface.