Install PyCalphad

The recommended method of installing PyCalphad depends on your preferred workflow. The common workflows can roughly be broken down into the following categories:

  • Project-based (e.g. uv, pixi) (recommended for new users)

  • Environment-based (e.g. pip, conda) (the traditional workflow)

  • Development version (building from source) (for contributing to PyCalphad)

Here is a step-by-step guide to setting up a project to use PyCalphad with uv, a Python package manager.

  1. Install uv by following the instructions in the uv documentation.

  2. Create a new project in a new subdirectory by running the following in a terminal:

    uv init try-pycalphad
cd try-pycalphad

    The second command changes directory into the directory of your project.

  3. Add PyCalphad to your project:

    uv add pycalphad

    This will automatically install Python if you don’t already have it installed.

  4. Try out PyCalphad!

    uv run python

    This will launch a Python interpreter session, from which you can import pycalphad.

Tip

You can install other Python libraries in the same way. For example, to run the PyCalphad examples in Jupyter notebooks:

uv add jupyterlab
uv run jupyter lab

Note

After rebooting your computer, you’ll want to navigate to your try-pycalphad project directory and run uv run python to drop back into a Python interpreter with PyCalphad importable. To run a Python script, you can use uv run myscript.py.

Read more in the uv guide to working on projects.

If you work with non-Python packages, you may prefer to install PyCalphad as a conda package, so that you can use the same workflow for packages which are not available on PyPI, the Python Package Index. Conda can manage packages in any language, so you can use it to install Python itself, compilers, and other languages.

The steps to install PyCalphad from conda-forge using pixi are very similar to the steps for uv:

  1. Install pixi by following the instructions in the pixi documentation.

  2. Create a new project in a new subdirectory:

    pixi init try-pycalphad
cd try-pycalphad

  3. Add PyCalphad to your project:

    pixi add pycalphad

  4. Try out PyCalphad!

    pixi run python

Tip

You can install other packages in the same way. For example, to run the PyCalphad examples in Jupyter notebooks:

pixi add jupyterlab
pixi run jupyter lab

In project-based workflows, a project is a directory containing a manifest file describing the project, a lock file describing the exact dependencies of the project, and the project’s (potentially multiple) environments. In contrast, in environment-based workflows you install packages into an environment, which you can activate and deactivate from any directory. These workflows are well-established, but lack some reproducibility benefits of project-based workflows.

  1. Install Python.

  2. A recommended best practice is to install PyCalphad into a virtual environment. To create and activate an environment called pycalphad-env on Linux and macOS:

    python -m venv pycalphad-env
source pycalphad-env/bin/activate

    On Windows, activate the environment by running pycalphad-env\Scripts\activate instead. This environment must be activated every time you use PyCalphad.

  3. Install PyCalphad from PyPI using pip:

    python -m pip install -U pycalphad

conda is a package manager that can install Python and non-Python packages. If you don’t have conda already, Miniforge is the recommended way to install it.

To create an environment called pycalphad-env with PyCalphad installed from conda-forge:

conda create -n pycalphad-env -c conda-forge pycalphad
conda activate pycalphad-env

This environment must be activated every time you use PyCalphad.

The source code for the latest development version of PyCalphad is available on GitHub. Development versions are built from source and installed in editable mode, which is mainly needed by users who wish to contribute to PyCalphad.

You will need a working version of git to download the source code and uv to install PyCalphad and its dependencies. Installing development versions of PyCalphad also requires a working C++ compiler.

To install an editable version of the latest development branch of PyCalphad, run:

git clone https://github.com/pycalphad/pycalphad.git
cd pycalphad
uv sync

Then run the automated tests to ensure everything installed correctly:

uv run pytest

The onboarding guide has detailed instructions for setting up a development environment, including installing the prerequisite tools, configuring VSCode, setting up your fork and remote repositories, building a local version of this website, and troubleshooting. Please read the contributing guide before submitting a pull request.

Upgrading

Changes to Python files (.py extension) in an editable install will be reflected as soon as a file is saved. Changes to Cython files (.pyx and .pxd extensions) must be recompiled before they take effect. uv recompiles the Cython files automatically the next time you run uv sync or uv run.

By default, the development version installed will track the latest changes in the develop branch of PyCalphad on GitHub.

To update the code in the current branch to the latest changes on GitHub, the changes are pulled from GitHub by running git pull.

To switch to a different branch, e.g. master (which tracks the latest released version) or another feature branch, run git checkout <branch>, where <branch> is the name of the branch to checkout, such as master (without the brackets < and >).

See next steps in the examples. Questions about installing and using PyCalphad can be addressed on the PyCalphad Discussion board.