Install & Compatibility
Where this runs
tested against v1.10.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.106s · 100.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 11.0s · import 1.014s · 104MB
105MB installed
● package 105MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
gto
✓ import gto
Primary import for accessing GTO's CLI and API functionality.
gto.api
✓ from gto import api
For direct programmatic access to GTO's operations like register, show, assign, etc.
This quickstart demonstrates how to use the `gto.api` to register an artifact and assign it to a stage within a Git repository. It simulates a basic Git workflow, registers 'my-model' from a 'model.pkl' file, and then promotes it to a 'dev' stage, finally showing the registry's state. Note that in a real scenario, `git push --tags` would be necessary to synchronize the GTO-managed tags with a remote repository.
import os
from pathlib import Path
import tempfile
import shutil
from gto import api
# Create a temporary directory for a mock Git repo
original_cwd = os.getcwd()
temp_dir = Path(tempfile.mkdtemp())
os.chdir(temp_dir)
try:
# Initialize a Git repository
os.system('git init -b main')
os.system('git config user.email "test@example.com"')
os.system('git config user.name "Test User"')
# Create a dummy artifact file
(temp_dir / "model.pkl").write_text("dummy_model_content")
os.system('git add .')
os.system('git commit -m "Initial commit with model.pkl"')
# Register a new version of an artifact
print("\n--- Registering artifact 'my-model' ---")
api.register("my-model", "model.pkl", type="model", description="My first model")
print("Artifact registered successfully.\n")
# Show the current state of the artifact registry
print("\n--- Showing artifact registry state ---")
registry_state = api.show(name="my-model", json=True)
print(registry_state)
# Promote the artifact to a 'dev' stage
print("\n--- Promoting 'my-model' to 'dev' stage ---")
api.assign("my-model", stage="dev", version="my-model@v0.0.1")
print("Artifact promoted to 'dev' stage successfully.\n")
# Show the updated state
print("\n--- Showing updated registry state ---")
updated_registry_state = api.show(name="my-model", json=True)
print(updated_registry_state)
# Important: Push the Git tags for changes to be reflected remotely
# In a real scenario: os.system('git push origin --tags')
finally:
os.chdir(original_cwd)
shutil.rmtree(temp_dir)
gto --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gto'
The 'gto' library is not installed in the current Python environment or the Python interpreter cannot find it in its search path.
fixInstall the library using pip: `pip install gto`
ImportError: cannot import name 'gto' from 'pyscf' (unknown location)
This error occurs when attempting to import 'gto', but the Python interpreter incorrectly finds a 'gto' module within the 'pyscf' library, or there's a naming conflict in the import path.
fixEnsure you are importing the correct 'gto' library and check for any custom modules or files named 'gto' in your project that might be shadowing the intended library. If you need to use both, explicitly import the desired one or rename conflicting local files.
gto annotate - Must provide artifact path from project root, relative path isn't resolved
When using `gto annotate`, the provided artifact path is interpreted relative to the current working directory, but the `gto` tool expects paths to be relative to the Git repository root.
fixRun `gto` commands from the project's root directory or provide the artifact path explicitly relative to the repository root.
ImportError: cannot import name 'gto' from partially initialized module 'gto' (most likely due to a circular import)
This error typically arises when a Python script file is named `gto.py`, causing a naming collision and leading Python to try importing the script itself instead of the installed `gto` library.
fixRename your Python script file to something other than `gto.py` (e.g., `my_gto_script.py`) to avoid shadowing the installed library.
Upgrade
Version history
1.10.1latest on PyPI · released Jul 9, 2026
Audit
Dependencies
pythonrequiredGTO requires Python 3.9 or higher.
pydanticrequiredUsed for data validation and settings management. Version 2.x is required since GTO 1.9.0.
scmreporequiredCore dependency for Git repository operations. Version 3.x is required since GTO 1.7.0.
dvcoptionalFrequently used alongside GTO to manage data and model files, serving as a backbone for Git-based Iterative Studio Model Registry.