Installation¶

Zaojun can be installed using several methods. Choose the one that best fits your workflow.

Prerequisites¶

Python 3.11 or higher
pip or uv package manager

Installation Methods¶

PyPI (Recommended)¶

Install Zaojun from PyPI using pip:

pip install zaojun

Or using uv (faster):

uv pip install zaojun

From Source¶

If you want to install the latest development version or contribute to Zaojun:

# Clone the repository
git clone https://codeberg.org/marvin8/zaojun.git
cd zaojun

# Install using uv (recommended)
uv sync

# Or install using pip in development mode
pip install -e .

Pre-commit Hook¶

Zaojun can be used as a pre-commit hook to automatically check dependencies before commits.

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://codeberg.org/marvin8/zaojun
    rev: 1.0.3  # Use the latest version
    hooks:
      - id: zaojun
        args:
          - "--groups"

Then install the hook:

pre-commit install

Verify Installation¶

After installation, verify that Zaojun is working correctly:

zaojun --version

You should see output similar to:

zaojun 1.0.3

Test the basic functionality:

zaojun --help

This will display the help text with all available options.

Development Installation¶

For contributing to Zaojun or running tests:

# Clone the repository
git clone https://codeberg.org/marvin8/zaojun.git
cd zaojun

# Install with development dependencies using uv
uv sync --all-groups

# Or using pip (development mode, no group deps)
pip install -e .

Development Dependencies¶

Zaojun uses several development tools:

ruff: Code formatting and linting
ty: Type checking
pytest: Testing framework
nox: Automated testing across Python versions
prek: Pre-commit hooks
bump-my-version: Version bumping
git-cliff: Changelog generation

Upgrading¶

To upgrade to the latest version:

pip install --upgrade zaojun

Or using uv:

uv pip install --upgrade zaojun

Uninstallation¶

If you need to remove Zaojun:

pip uninstall zaojun

Or using uv:

uv pip uninstall zaojun

Platform Support¶

Zaojun works on all major platforms:

Linux: Fully supported
macOS: Fully supported
Windows: Fully supported (via WSL recommended for best experience)

Python Version Support¶

Zaojun supports Python 3.11 and higher. It's tested against:

Python 3.11
Python 3.12
Python 3.13
Python 3.14

Troubleshooting¶

Common Issues¶

Permission errors during installation

# Use user installation
pip install --user zaojun

# Or use a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install zaojun

Command not found after installation
Ensure Python's Scripts directory is in your PATH
On Linux/macOS: ~/.local/bin
On Windows: %APPDATA%\Python\Scripts
Network issues accessing PyPI
Check your internet connection
Verify PyPI is accessible: curl https://pypi.org
Use a mirror if needed

Getting Help¶

If you encounter issues:

Check the Codeberg Issues for known problems
Run with verbose output: zaojun --help
Ensure you have the latest version: zaojun --version

Next Steps¶

Once installed, check out the Quick Start guide to begin using Zaojun. Full documentation is available at marvin8.codeberg.page/zaojun.