Skip to content

Installation

This guide will help you install Nauyaca on your system. Choose the installation method that best fits your needs.

Prerequisites

Before installing Nauyaca, ensure you have:

  • Python 3.10 or higher installed on your system
  • pip (included with Python) or uv (recommended for faster installations)

Why uv?

uv is a modern, extremely fast Python package manager written in Rust. It's 10-100x faster than pip and provides better dependency resolution. We recommend using uv for the best experience.

Checking Your Python Version

python --version

You should see Python 3.10.x or higher. If not, download the latest version from python.org.

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

pip install uv

Installation Methods

This is the recommended method if you want to use Nauyaca primarily as a command-line tool for running servers and clients.

uv tool install nauyaca

This installs the nauyaca command globally, making it available from anywhere on your system.

pipx install nauyaca

pipx is similar to uv tool install - it installs CLI tools in isolated environments.

After installation, verify it works:

nauyaca --help

You should see the Nauyaca command-line interface help text.

Method 2: Install as a Library

This method is best if you want to use Nauyaca in your own Python projects or applications.

# Create a new project
uv init my-gemini-project
cd my-gemini-project

# Add nauyaca as a dependency
uv add nauyaca

# Add to your existing project
uv add nauyaca

# In a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install nauyaca

# Or install system-wide (not recommended)
pip install nauyaca

Method 3: Install from Source (Development)

This method is for developers who want to contribute to Nauyaca or test the latest unreleased features.

# Clone the repository
git clone https://github.com/alanbato/nauyaca.git
cd nauyaca

# Install with development dependencies
uv sync

Development Installation

Installing from source gives you the latest development version, which may be unstable. For production use, install from PyPI using Method 1 or 2.

Verifying Your Installation

After installation, verify that Nauyaca is working correctly:

Check the Version

nauyaca version

Expected output: 

Nauyaca version 0.2.0

Run the Help Command

nauyaca --help

You should see output similar to:

Usage: nauyaca [OPTIONS] COMMAND [ARGS]...

  Nauyaca - Modern Gemini Protocol Server & Client

Commands:
  serve    Start a Gemini server
  get      Fetch a Gemini resource
  cert     Certificate management
  tofu     Manage TOFU database
  version  Show version information

Test the Client

Try fetching a resource from a public Gemini server:

nauyaca get gemini://geminiprotocol.net/

First Connection

On your first connection to a server, you'll be prompted to trust the certificate (TOFU - Trust On First Use). This is normal and expected.

Optional: Shell Completion

Nauyaca supports shell completion for Bash, Zsh, and Fish. This provides tab-completion for commands and options.

# Add to ~/.bashrc
eval "$(_NAUYACA_COMPLETE=bash_source nauyaca)"

Then reload your shell: 

source ~/.bashrc


# Add to ~/.zshrc
eval "$(_NAUYACA_COMPLETE=zsh_source nauyaca)"

Then reload your shell: 

source ~/.zshrc


# Add to ~/.config/fish/completions/nauyaca.fish
_NAUYACA_COMPLETE=fish_source nauyaca | source

Then reload your shell: 

source ~/.config/fish/config.fish

Development Setup

If you're planning to contribute to Nauyaca or develop with the source code, follow these additional steps:

1. Clone and Install

# Clone the repository
git clone https://github.com/alanbato/nauyaca.git
cd nauyaca

# Install with development dependencies
uv sync

2. Verify the Test Suite

Run the test suite to ensure everything is working:

uv run pytest

Expected output: 

================================ test session starts ================================
...
================================ XX passed in X.XXs =================================

3. Run Code Quality Checks

# Run linting
uv run ruff check src/ tests/

# Run type checking
uv run mypy src/

# Run tests with coverage
uv run pytest --cov=src/nauyaca --cov-report=html

4. Pre-commit Hooks (Optional)

Install pre-commit hooks to automatically run checks before each commit:

uv run pre-commit install

Troubleshooting

Python Version Issues

Problem: nauyaca command not found after installation

Solution: Ensure your Python bin directory is in your PATH:

# For uv tool install
export PATH="$HOME/.local/bin:$PATH"

# Add to ~/.bashrc or ~/.zshrc to make permanent
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Add %USERPROFILE%\AppData\Local\bin to your PATH environment variable.

SSL/TLS Certificate Errors

Problem: Certificate verification errors when connecting to servers

Solution: This is usually due to self-signed certificates. Nauyaca uses TOFU validation, so you'll need to trust certificates on first use:

# Manually trust a certificate
nauyaca tofu trust geminiprotocol.net

Import Errors in Python

Problem: ModuleNotFoundError: No module named 'nauyaca'

Solution: Ensure you've installed nauyaca in your current Python environment:

# Check if nauyaca is installed
pip list | grep nauyaca

# If not found, install it
uv add nauyaca  # or: pip install nauyaca

Permission Errors

Problem: Permission denied errors during installation

Solution:

  • Don't use sudo with pip - Use a virtual environment instead
  • For uv tool install - No sudo needed, installs to user directory
  • If you must install system-wide - Consider using your OS package manager

Upgrading Nauyaca

To upgrade to the latest version:

uv tool upgrade nauyaca

pip install --upgrade nauyaca

cd nauyaca
git pull origin main
uv sync

Uninstalling

If you need to remove Nauyaca:

uv tool uninstall nauyaca

pip uninstall nauyaca

Simply delete the cloned repository directory: 

rm -rf nauyaca

Next Steps

Now that you have Nauyaca installed, you can:

See Also