Install#

PythTB ≥ 2.0.0 supports Python ≥ 3.12 (see SPEC-0).
Versions up to v1.8.0 are compatible with Python 2.7–3.10, while v1.7.0 and below are limited to Python 2.x. Although other versions may work, they are not officially supported.

To check your Python version, run:

python -V

If you do not have Python 3.12 or higher, see Installing or Upgrading Python below. If you are unfamiliar with Python see our resources.

Dependencies#

PythTB requires:

Optional extras (install via pip install .[group]):

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

  • [speedup]: tensorflow

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

  • [docs]: sphinx toolchain for building documentation

  • [tests]: pytest

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

Quick Installation#

You can install PythTB directly from either PyPI or Conda-Forge.

# Using pip
pip install pythtb --upgrade

# Or using conda
conda install -c conda-forge pythtb

Verify installation:

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

If you encounter issues or missing dependencies, see Troubleshooting.

Installing from Source#

If you’d like to install PythTB from source, you can do so by cloning the repository from GitHub. This is useful if you want to contribute to the project or if you want to use the latest development version.

  1. Clone the repository:

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

  1. Install the package:

pip install .

This installs PythTB and its dependencies into your current Python environment. If you want to install PythTB with optional dependencies, you can run

pip install .[group] # replace [group] with optional groups as needed

Editable (Development) Installation#

For contributors or developers who wish to modify the source code and see changes take effect immediately, install in editable mode:

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

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

  1. Clone and install in editable mode by using the -e flag:

git clone https://github.com/pythtb/pythtb.git
cd pythtb
pip install -e .[group]  # replace [group] with optional groups as needed

  1. Verify installation:

import pythtb
print(pythtb.__version__)

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, see the Developer Installation Wiki.

Older Versions#

PyPI and Conda-Forge always host the latest stable release of PythTB. Conda-Forge allows installing specific versions using:

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

To list installed versions:

pip show pythtb

Or in Python:

import pythtb
print(pythtb.__version__)

All previous releases of PythTB can be found below in Version List and the source code can be downloaded from the links provided there.

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)#

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