Installation

Requirements

  • Python 3.7 or higher

  • pip (Python package installer)

Install from PyPI

The easiest way to install Vargula is using pip:

pip install vargula

Upgrade to Latest Version

To upgrade to the latest version:

pip install --upgrade vargula

Install Specific Version

To install a specific version:

pip install vargula==1.1.0

Install from Source

Clone the repository and install in development mode:

git clone https://github.com/crystallinecore/vargula.git
cd vargula
pip install -e .

This allows you to modify the source code and see changes immediately.

Verify Installation

Check that Vargula is installed correctly:

from vargula import Vargula
vg = Vargula()
print(vg.__version__)
# Output: 1.1.0

Test basic functionality:

from vargula import Vargula
vg = Vargula()

# Test color output
print(vg.style("Hello, Vargula!", color="cyan", look="bold"))

# Test markup
vg.write("<red>Red text</red> and <blue>blue text</blue>")

# Test palette generation
palette = vg.generate_palette("#3498db", "complementary", 3)
print(palette)

If you see colored output, everything is working correctly!

Platform-Specific Notes

Windows

Vargula automatically enables ANSI color support on Windows 10 and later. For older versions of Windows:

  • Use Windows Terminal (recommended)

  • Or enable ANSI support in Command Prompt manually

  • Or use ConEmu or similar terminal emulators

# Vargula handles this automatically
from vargula import Vargula
# Colors work out of the box on Windows 10+
vg = Vargula()

macOS

No additional setup required. Works perfectly in:

  • Terminal.app

  • iTerm2

  • Any other macOS terminal emulator

Linux

No additional setup required. Works in all modern terminal emulators:

  • GNOME Terminal

  • Konsole

  • xterm

  • Alacritty

  • kitty

  • And many more

Dependencies

Vargula has zero external dependencies. It uses only Python standard library modules:

  • sys - System-specific parameters

  • os - Operating system interfaces

  • re - Regular expressions

  • colorsys - Color system conversions

  • json - JSON encoding/decoding

  • pathlib - Object-oriented filesystem paths

  • contextlib - Context manager utilities

  • typing - Type hints support

  • random - Random number generation

This means:

  • ✓ Fast installation

  • ✓ No dependency conflicts

  • ✓ Minimal security surface

  • ✓ Works anywhere Python works

Development Installation

For contributors and developers:

# Clone repository
git clone https://github.com/crystallinecore/vargula.git
cd vargula

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Check code quality
flake8 vargula

Uninstallation

To remove Vargula:

pip uninstall vargula

Troubleshooting

Colors Not Showing

If colors aren’t displaying:

  1. Check if output is a TTY:

    import sys
print(sys.stdout.isatty())  # Should be True

  2. Force color output:

    FORCE_COLOR=1 python your_script.py

  3. Check NO_COLOR variable:

    # Make sure NO_COLOR is not set
echo $NO_COLOR

Windows ANSI Issues

If colors don’t work on Windows:

  1. Update to Windows 10 or later

  2. Use Windows Terminal instead of cmd.exe

  3. Try forcing ANSI support:

    from vargula import Vargula
vg = Vargula()
vg.enable()  # Force enable colors

Import Errors

If you get import errors:

# Check Python version
python --version  # Should be 3.7+

# Verify installation
pip show vargula

# Reinstall
pip uninstall vargula
pip install vargula

Next Steps

Now that Vargula is installed, continue with: