Migrating from jgo 1.x

This guide covers upgrading from jgo 1.x to 2.x. jgo 2.x maintains backward compatibility – your existing scripts and code will continue to work, with deprecation warnings guiding you toward the new APIs.

Backward compatibility

jgo 2.x preserves backward compatibility through:

Deprecated Python API – All old functions and classes still work but emit deprecation warnings.
Deprecated CLI flags – Old flags are aliased to new ones with warnings.

Deprecated APIs will be removed in jgo 3.0.

Python API changes

Old API (deprecated)

import jgo

# These still work but show deprecation warnings
jgo.main(["org.scijava:parsington"])
jgo.resolve_dependencies("org.scijava:parsington", cache_dir="/tmp")
jgo.main_from_endpoint("org.scijava:parsington")

New API

import jgo

# Simple high-level functions
jgo.run("org.scijava:parsington", app_args=["--help"])
env = jgo.build("org.scijava:parsington")
components = jgo.resolve("org.scijava:parsington")

Migration table

Old (1.x)	New (2.x)
`jgo.main(argv)`	`jgo.run(endpoint, app_args=...)`
`jgo.main_from_endpoint(ep, ...)`	`jgo.run(endpoint, ...)`
`jgo.resolve_dependencies(ep, ...)`	`jgo.resolve(endpoint, ...)`
`from jgo.jgo import resolve_dependencies`	`import jgo; jgo.resolve(...)`
`from jgo.util import main_from_endpoint`	`import jgo; jgo.run(...)`

Advanced: layered API

jgo 1.x had a single monolithic module. jgo 2.x provides three independently useful layers:

from jgo.maven import MavenContext
from jgo.env import EnvironmentBuilder
from jgo.exec import JavaRunner

# Layer 1: Dependency resolution (no Maven installation needed!)
maven = MavenContext()
component = maven.project("org.python", "jython-standalone").at_version("2.7.3")

# Layer 2: Environment materialization
builder = EnvironmentBuilder(context=maven)
env = builder.from_endpoint("org.python:jython-standalone:2.7.3")

# Layer 3: Execution
runner = JavaRunner()
runner.run(env)

See Python API for full details.

CLI changes

Commands replace flags

jgo 2.x uses a command-based CLI. The old endpoint-first syntax still works:

# Both work -- the first auto-detects the 'run' command
jgo org.python:jython-standalone
jgo run org.python:jython-standalone

New commands for project management and inspection:

jgo init org.python:jython-standalone    # Create jgo.toml
jgo add org.slf4j:slf4j-simple           # Add dependency
jgo remove org.slf4j:slf4j-simple        # Remove dependency
jgo list                                  # List dependencies
jgo tree                                  # Show dependency tree
jgo info classpath ENDPOINT              # Show classpath
jgo search apache commons                # Search Maven Central
jgo config shortcut imagej net.imagej:imagej  # Manage shortcuts

Permanent short flags

These short flags are permanent aliases and will not be removed:

Short	Long	Description
`-v`	`--verbose`	Verbose output
`-q`	`--quiet`	Quiet mode
`-u`	`--update`	Update cache
`-r`	`--repository`	Add repository
`-f`	`--file`	Use specific jgo.toml

Deprecated flags

Old flag	New replacement	Notes
`-U`, `--force-update`	`-u`, `--update`	Both now check remote repos
`-a`, `--additional-jars`	`--add-classpath`	Handles JARs and directories
`--additional-endpoints`	`+` syntax	e.g., `g:a+g2:a2`
`--link-type`	`--links`	Matches config field name
`--log-level`	`-v`/`-vv`/`-vvv`	Use verbose flags
`--print-classpath`	`jgo info classpath`	Now a subcommand
`--print-dependency-tree`	`jgo tree`	Now a subcommand
`--print-dependency-list`	`jgo list`	Now a subcommand
`--list-versions`	`jgo info versions`	Now a subcommand

Update behavior change

In jgo 1.x, -u and -U were different. In jgo 2.x:

# jgo 1.x
jgo -u endpoint    # Rebuild from local cache
jgo -U endpoint    # Check remote repositories and rebuild

# jgo 2.x
jgo -u --offline endpoint   # Rebuild from local (old -u behavior)
jgo -u endpoint              # Check remote and rebuild (old -U behavior)

Configuration changes

Cache directory

	Location
jgo 1.x	`~/.jgo`
jgo 2.x	`~/.cache/jgo` (Linux/macOS), `%LOCALAPPDATA%\jgo` (Windows)

Old cache directories are not migrated automatically. jgo 2.x creates a fresh cache.

Settings file

The INI format is unchanged. jgo 2.x adds a new preferred location:

~/.config/jgo.conf (XDG standard – new, recommended)
~/.jgorc (legacy – still works)

Your existing ~/.jgorc will continue to work. Use --ignore-config to skip the settings file.

Breaking changes

These are the only behaviors that differ from 1.x in a non-backward-compatible way:

Cache location – ~/.jgo is no longer used by default. Override with --cache-dir ~/.jgo or JGO_CACHE_DIR=~/.jgo if needed.
-u checks remote – The old -u (local-only rebuild) now requires --update --offline.
Java version pinning in AUTO mode – In AUTO mode (the default), jgo 2.x first checks whether a suitable Java already exists on the system (JAVA_HOME or PATH). “Suitable” means the installed version meets the minimum requirement detected from bytecode; if so, it is used directly and no download occurs. Only when no suitable system Java is found does jgo download and cache one via cjdk. In jgo 1.x the equivalent behaviour was provided by the standalone cjdk tool. The practical difference is that specifying java_version="11" (or --java-version 11) is now treated as a minimum (“11 or higher”) rather than an exact pin when a system Java is present; the exact pin only applies when cjdk is invoked as a fallback. To force the use of your own Java installation and never download, use --system-java on the CLI or java_source="system" in the Python API.

New features in 2.x

jgo.toml project files

Reproducible environments with lock files:

[environment]
name = "my-project"

[dependencies]
coordinates = ["net.imagej:imagej:2.15.0"]

[entrypoints]
default = "net.imagej.Main"

jgo           # Run from jgo.toml
jgo sync      # Rebuild environment
jgo update    # Update dependencies

See Project Mode with jgo.toml for details.

Automatic Java management

No need to pre-install Java. jgo detects bytecode requirements, then locates or downloads the correct version automatically:

jgo net.imagej:imagej    # Uses system Java if >= 17; downloads Java 17 otherwise

In AUTO mode (the default), jgo checks JAVA_HOME and PATH first. A cjdk- managed JDK is downloaded only when no suitable Java is found on the system. Use --system-java to restrict jgo to system Java only (error if absent or too old), or set java_source="system" in the Python API.

Pure Python resolver

Resolve Maven dependencies without a Maven installation:

jgo --resolver python org.python:jython-standalone

Three-layer architecture

Each layer is independently useful for dependency analysis, IDE integration, or custom launchers. See Architecture for details.

Testing your migration

Run with deprecation warnings visible:

python -W default::DeprecationWarning -m jgo org.python:jython-standalone

Gradually replace deprecated calls:

# Before
jgo.main_from_endpoint("org.python:jython-standalone")

# After
jgo.run("org.python:jython-standalone")