Developing¶

If you wish to develop for TagStudio, you'll need to create a development environment by installing the required dependencies. You have a number of options depending on your level of experience and familiarity with existing Python toolchains.

Contributing

If you wish to contribute to TagStudio's development, please read our CONTRIBUTING.md!

Install Python¶

Python 3.12 is required to develop for TagStudio. Any version matching "Python 3.12.x" should work, with "x" being any number. Alternatively you can use a tool such as pyenv to install this version of Python without affecting any existing Python installations on your system. Tools such as uv can also install Python versions.

Python Aliases

Depending on your system, Python may be called python, py, python3, or py3. These instructions use the alias python for consistency.

If you already have Python installed on your system, you can check the version by running the following command:

python --version

Installing with pyenv¶

If you choose to install Python using pyenv, please refer to the following instructions:

Follow pyenv's install instructions for your system.
Install the appropriate Python version with pyenv by running pyenv install 3.12 (This will not mess with your existing Python installation).
Navigate to the repository root folder in your terminal and run pyenv local 3.12. You could alternatively use pyenv shell 3.12 or pyenv global 3.12 instead to set the Python version for the current terminal session or the entire system respectively, however using local is recommended.

Installing Dependencies¶

To install the required dependencies, you can use a dependency manager such as uv or Poetry 2.0. Alternatively you can create a virtual environment and manually install the dependencies yourself.

Installing with uv¶

If using uv, you can install the dependencies for TagStudio with the following command:

uv pip install -e .[dev]

A reference .envrc is provided for use with direnv, see contrib/.envrc-uv.

Installing with Poetry¶

If using Poetry, you can install the dependencies for TagStudio with the following command:

poetry install --with dev

Manual Installation¶

If you choose to manually set up a virtual environment and install dependencies instead of using a dependency manager, please refer to the following instructions:

Virtual Environments

Learn more about setting up a virtual environment with Python's official tutorial.

In the root repository directory, create a python virtual environment:
```
python -m venv .venv
```
Activate your environment:
- Windows w/Powershell: .venv\Scripts\Activate.ps1
- Windows w/Command Prompt: .venv\Scripts\activate.bat
- Linux/macOS: source .venv/bin/activate
Supported Shells

Depending on your system, the regular activation script might not work on alternative shells. In this case, refer to the table below for supported shells:

Shell Script

Bash/ZSH .venv/bin/activate

Fish .venv/bin/activate.fish

CSH/TCSH .venv/bin/activate.csh

PowerShell .venv/bin/activate.ps1
Use the following PIP command to create an editable installation and install the required development dependencies:
```
pip install -e .[dev]
```

Nix(OS)¶

If using Nix, there is a development environment already provided in the flake that is accessible with the following command:

nix develop

A reference .envrc is provided for use with direnv, see contrib/.envrc-nix.

Tooling¶

Editor Integration¶

The entry point for TagStudio is src/tagstudio/main.py. You can target this file from your IDE to run or connect a debug session. The example(s) below show off example launch scripts for different IDEs. Here you can also take advantage of launch arguments to pass your own test libraries to use while developing. You can find more editor configurations in contrib.

VS Code

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "TagStudio",
            "type": "python",
            "request": "launch",
            "program": "${workspaceRoot}/src/tagstudio/main.py",
            "console": "integratedTerminal",
            "justMyCode": true,
            "args": ["-o", "~/Documents/Example"]
        }
    ]
}

pre-commit¶

There is a pre-commit configuration that will run through some checks before code is committed. Namely, mypy and the Ruff linter and formatter will check your code, catching those nits right away.

Once you have pre-commit installed, just run:

pre-commit install

From there, Git will automatically run through the hooks during commit actions!

direnv¶

You can automatically enter this development shell, and keep your user shell, with a tool like direnv. Some reference .envrc files are provided in the repository at contrib.

Two currently available are for Nix and uv, to use one:

ln -s .envrc-$variant .envrc

You will have to allow usage of it.

direnv Security Framework

These files are generally a good idea to check, as they execute commands on directory load. direnv has a security framework to only run .envrc files you have allowed, and does keep track on if it has changed. So, with that being said, the file may need to be allowed again if modifications are made.

cat .envrc # You are checking them, right?
direnv allow

Building¶

To build your own executables of TagStudio, first follow the steps in "Installing Dependencies." Once that's complete, run the following PyInstaller command:

pyinstaller tagstudio.spec

If you're on Windows or Linux and wish to build a portable executable, then pass the following flag:

pyinstaller tagstudio.spec -- --portable

The resulting executable file(s) will be located in a new folder named "dist".

Shell	Script
Bash/ZSH	`.venv/bin/activate`
Fish	`.venv/bin/activate.fish`
CSH/TCSH	`.venv/bin/activate.csh`
PowerShell	`.venv/bin/activate.ps1`