Install#

PythTB can be installed in a variety of ways depending on your workflow. This page covers system requirements, quick installation methods, and optional developer setups.

Dependencies#

PythTB follows the SPEC-0 support window for scientific Python packages.

Required dependencies:

Optional extras (install via pip install .[$GROUP]):

  • [plotting]: plotly (interactive 3D plots)

  • [speedup]: tensorflow

  • [notebooks]: ipython ≥ 8.17, ipykernel, notebook ≥ 7.0, jupyter, jupyterlab

  • [docs]: sphinx toolchain for building documentation

  • [tests]: pytest

  • [dev]: pytest, black, ruff, pre-commit, nbstripout

Check your Python version by running:

python -V

If you need to upgrade Python, see Installing or Upgrading Python below. If you are new to Python see our resources.

Quick Installation#

Install PythTB from PyPI or conda-forge.

# Using pip
pip install pythtb --upgrade

# Using conda
conda install -c conda-forge pythtb

Verify installation:

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

If you encounter issues, see Troubleshooting.

Installing from Source#

Installing from source is recommended for contributors or for using the latest development version.

  1. Create a virtual environment using conda (recommended):

conda create -n pythtb-dev python=3.12
conda activate pythtb-dev

  1. Clone the repository:

git clone https://github.com/pythtb/pythtb.git
cd pythtb

  1. Install the package along with any optional dependencies you need:

pip install .  # or pip install .[$GROUP] for optional dependencies

For an editable install,

pip install -e .

Editable installs allow immediate reflection of code changes. If you modify the source code, those changes will immediately take effect in your local environment. If you don’t see updates reflected, restart the interpreter or Jupyter kernel.

For more details about setting up your development environment, see the Developer Installation Wiki.

Older Versions#

The latest stable release is always available on PyPI and conda-forge.

Install a specific version using conda:

conda install -c conda-forge pythtb=X.Y.Z

Note

Currently only PythTB >= 1.8.0 are available on Conda-Forge.

Using pip, you can install all older versions from PyPI:

pip install pythtb==X.Y.Z

Check the installed version with:

pip show pythtb

The source code of all previous releases of PythTB can be downloaded below in Version List.

Verify installation#

After installation, verify by running:

import pythtb
print(pythtb.__version__)

This should print the installed version of PythTB without errors.

Installing or Upgrading Python#

If you don’t already have Python 3.12 or higher, follow one of the options below.

macOS and Linux#

Use your system’s package manager:

# Ubuntu / Debian
sudo apt-get install python3

# macOS (via Homebrew)
brew install python

Alternatively, download the latest release from the official Python website.

Windows#

Download and run the official installer from python.org. Make sure to check “Add Python to PATH” during installation.

Troubleshooting#

Common issues and fixes:

  • ModuleNotFoundError

    Make sure you are using the correct Python environment where PythTB is installed. If using conda, activate the environment:

    conda activate your-env-name

    Check installation with:

    conda list | grep pythtb

  • Conflicting installations

    If you have multiple installations of PythTB, uninstall them first:

    pip uninstall pythtb
conda remove pythtb

    Then reinstall using one method (pip or conda).

  • Conflicts between pip and conda

    Avoid mixing pip and conda installations in the same environment. Prefer using one package manager consistently. The exception is using pip to install packages not available via conda or when installing in editable mode.

  • Editable mode issues

    If you installed PythTB in editable mode and changes are not reflected, restart your Python interpreter or Jupyter kernel. Make sure you installed with the -e flag:

    pip install -e .

If problems persist, open an issue on the GitHub repository.

Version List#

See changelog for a complete list of changes.

Version 2.0.0 (current)#

11 November 2025: pythtb-2.0.0.tar.gz

Version 1.8.0#

20 September 2022: pythtb-1.8.0.tar.gz

Version 1.7.2#

1 August 2017: pythtb-1.7.2.tar.gz

Version 1.7.1#

22 December 2016: pythtb-1.7.1.tar.gz

Version 1.7.0#

7 June 2016: pythtb-1.7.0.tar.gz

Version 1.6.2#

25 February 2013: pythtb-1.6.2.tar.gz

Version 1.6.1#

15 November 2012: pythtb-1.6.1.tar.gz

Version 1.5#

4 June 2012: pytb-1.5.tar.gz