Skip to content

Installation Guide

Get Rxiv-Maker running on your system in minutes. We support all major platforms with simple, reliable installation methods.

pipx is the recommended installation method for all users:

  • ✅ Isolated environments: No conflicts with other Python packages
  • ✅ Automatic PATH setup: Commands available system-wide
  • ✅ Easy updates: Simple upgrade process
  • ✅ Clean uninstall: Complete removal when needed

Quick Installation

# Install using pipx (recommended)
pipx install rxiv-maker

# Verify installation
rxiv check-installation

# Ubuntu/Debian
sudo apt update
sudo apt install python3-pip pipx texlive-latex-recommended
pipx install rxiv-maker

# Red Hat/CentOS/Fedora
sudo dnf install python3-pip texlive-latex
python3 -m pip install --user pipx
pipx install rxiv-maker

# Verify
rxiv check-installation

# Install Homebrew (if needed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install pipx
brew install --cask mactex-no-gui

# Install rxiv-maker
pipx install rxiv-maker
rxiv check-installation

Option 1: WSL2 (Recommended) 

# Install WSL2 (PowerShell as Administrator)
wsl --install -d Ubuntu-22.04

# Restart, then in Ubuntu:
sudo apt update
sudo apt install python3-pip pipx texlive-latex-recommended
pipx install rxiv-maker

Option 2: Native Windows 

# Install Chocolatey (PowerShell as Administrator)
Set-ExecutionPolicy Bypass -Scope Process -Force
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install dependencies
choco install python pipx miktex
pipx install rxiv-maker

Alternative Installation Methods

Using pip

If you prefer pip over pipx:

# Install globally
pip install rxiv-maker

# Or in a virtual environment (recommended for development)
python -m venv rxiv-env
source rxiv-env/bin/activate  # On Windows: rxiv-env\Scripts\activate
pip install rxiv-maker

Development Installation

For contributing or using the latest features:

# Clone repository
git clone https://github.com/HenriquesLab/rxiv-maker.git
cd rxiv-maker

# Install in development mode
pip install -e ".[dev]"

# Run tests to verify
nox -s test-fast

Verification

After installation, verify everything is working:

# Check basic installation
rxiv --version
rxiv --help

# Comprehensive system check
rxiv check-installation

# Detailed verification with troubleshooting info
rxiv check-installation --detailed

Expected output: 

✅ Rxiv-Maker 1.0.0 installed successfully
✅ Python 3.11.0 found
✅ LaTeX distribution detected
✅ Required packages available
✅ System ready for PDF generation

Quick Test

Create your first manuscript to verify everything works:

# Create test manuscript
rxiv init test-paper
cd test-paper

# Generate PDF
rxiv pdf

# Check output
ls -la OUTPUT/

You should see manuscript.pdf in the OUTPUT directory.

System Requirements

Minimum Requirements

  • Python: 3.10 or later
  • Disk Space: 1 GB free space
  • Memory: 2 GB RAM (4 GB recommended)
  • LaTeX: Any modern distribution (TeXLive, MiKTeX, MacTeX)

Supported Platforms

Platform Support Level Notes
Ubuntu 20.04+ ✅ Full Primary development platform
Debian 11+ ✅ Full Well tested
CentOS/RHEL 8+ ✅ Full Enterprise ready
Fedora 35+ ✅ Full Latest packages
macOS 11+ ✅ Full Intel and Apple Silicon
Windows 10+ ✅ Via WSL2 Recommended approach
Windows 10+ ⚠️ Native Limited testing

LaTeX Distributions

Rxiv-Maker works with any modern LaTeX distribution:

  • Linux: TeXLive (recommended)
  • macOS: MacTeX or BasicTeX
  • Windows: MiKTeX or TeXLive

Installation guided automatically by rxiv check-installation.

Post-Installation Setup

VS Code Extension

Enhance your editing experience:

  1. Install VS Code
  2. Install the Rxiv-Maker extension
  3. Open your manuscript folder in VS Code

Learn more about the VS Code extension →

Shell Completion

Enable command autocompletion:

# Bash
echo 'eval "$(_RXIV_COMPLETE=bash_source rxiv)"' >> ~/.bashrc

# Zsh
echo 'eval "$(_RXIV_COMPLETE=zsh_source rxiv)"' >> ~/.zshrc

# Fish
rxiv --shell-completion fish > ~/.config/fish/completions/rxiv.fish

Environment Variables

Optional configuration:

# Set default engine (local is default)
export RXIV_ENGINE=local

# Custom cache directory
export RXIV_CACHE_DIR="$HOME/.cache/rxiv-maker"

# Enable debug output
export RXIV_DEBUG=1

Updating Rxiv-Maker

Keep your installation current:

# Update with pipx
pipx upgrade rxiv-maker

# Update with pip
pip install --upgrade rxiv-maker

# Check version after update
rxiv --version

Release Channels

  • Stable: Default installation, thoroughly tested
  • Beta: Early access to new features
  • Development: Latest code from main branch
# Install beta releases
pipx install rxiv-maker --include-deps --pip-args="--pre"

# Install from development branch
pipx install git+https://github.com/HenriquesLab/rxiv-maker.git

Uninstallation

If you need to remove Rxiv-Maker:

# Uninstall with pipx
pipx uninstall rxiv-maker

# Uninstall with pip
pip uninstall rxiv-maker

# Remove configuration (optional)
rm -rf ~/.config/rxiv-maker
rm -rf ~/.cache/rxiv-maker

Docker Alternative

For containerized environments or complex dependencies:

# Use the separate Docker repository
git clone https://github.com/HenriquesLab/docker-rxiv-maker.git
cd docker-rxiv-maker

# Build and run
docker build -t rxiv-maker .
docker run -v $(pwd):/workspace rxiv-maker

Learn more about Docker deployment →

Cloud Platforms

Google Colab

Try Rxiv-Maker without local installation:

Open in Colab

GitHub Actions

Automated manuscript building:

# .github/workflows/build-manuscript.yml
name: Build Manuscript
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install Rxiv-Maker
        run: pipx install rxiv-maker
      - name: Build PDF
        run: rxiv pdf
      - name: Upload PDF
        uses: actions/upload-artifact@v3
        with:
          name: manuscript
          path: OUTPUT/manuscript.pdf

Troubleshooting

Common Issues

Command not found: 

# Ensure pipx bin directory is in PATH
pipx ensurepath
source ~/.bashrc  # or restart terminal

LaTeX errors: 

# Check LaTeX installation
rxiv check-installation --detailed
# Follow specific guidance for your system

Permission errors: 

# Use pipx instead of pip
pipx install rxiv-maker
# Avoid sudo with pip

Python version issues: 

# Check Python version
python --version
# Ensure Python 3.10 or later

Getting Help

If you encounter issues:

  1. Check the troubleshooting guide: Troubleshooting →
  2. Run diagnostic command: rxiv check-installation --detailed
  3. Search existing issues: GitHub Issues
  4. Ask the community: GitHub Discussions

Next Steps

Once installation is complete:

  • Create Your First Manuscript

    Learn the basics with a simple example

    First Manuscript

  • Explore Features

    Discover what makes Rxiv-Maker powerful

    User Guide

  • VS Code Extension

    Set up the ultimate editing environment

    VS Code Setup

  • Examples

    Learn from real-world manuscripts

    Examples

Ready to Write

Installation complete! You're now ready to create professional scientific manuscripts with Rxiv-Maker.