Installation

Get SyftPerm installed and configured on your system in just a few steps.

Quick Install

Install SyftPerm from PyPI with pip:

pip install syft-perm
✅ That's it! SyftPerm is now ready to use. Jump to the Quick Start guide to begin.

Installation Options

🎯 Core Package

Basic SyftPerm functionality for file permission management:

pip install syft-perm

Includes:

  • Core permission management
  • Pattern matching system
  • YAML configuration
  • Debugging tools

🚀 Full Package (Recommended)

Complete SyftPerm experience with all optional features:

pip install "syft-perm[server,display]"

Includes everything above plus:

  • Web-based permission editor
  • Rich table display in Jupyter
  • Interactive HTML representations
  • FastAPI server for UI

Optional Dependencies

You can also install specific optional features individually:

Server Features
pip install "syft-perm[server]"

Adds the interactive web-based permission editor. Perfect for teams with non-technical members who need to manage permissions through a user-friendly interface.

Display Features
pip install "syft-perm[display]"

Enhanced table formatting for Jupyter notebooks and terminals. Makes permission tables much more readable during development and debugging.

SyftBox Integration
pip install "syft-perm[syftbox]"

Deep integration with SyftBox core libraries. Required only if you're extending SyftBox itself or building custom SyftBox applications.

System Requirements

📋 Minimum Requirements

  • Python: 3.9 or higher
  • Operating System: Windows, macOS, or Linux
  • Memory: 50MB RAM
  • Disk: 10MB storage

🎯 Recommended Setup

  • Python: 3.10+ for best performance
  • Package Manager: pip 21+ or uv
  • Environment: Virtual environment
  • Editor: Jupyter notebooks for tutorials

Development Installation

Want to contribute to SyftPerm or work with the source code? Follow these steps:

🔧 Prerequisites

  • Git installed on your system
  • Python 3.9 or higher
  • Virtual environment (recommended)
  • Basic command line knowledge

⚡ Quick Setup

Get up and running in under 2 minutes:

  1. Clone the repository
  2. Install dependencies
  3. Run tests
  4. Start coding!
Step 1: Clone the Repository
git clone https://github.com/OpenMined/syft-perm.git cd syft-perm
Step 2: Create Virtual Environment (Recommended)
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
Step 3: Install in Development Mode
pip install -e ".[dev,server,display]"

This installs SyftPerm in editable mode with all development dependencies including:

  • dev: Testing frameworks, linters, build tools, and notebook testing tools (nbformat, nbconvert, ipykernel)
  • server: Web UI dependencies
  • display: Enhanced table formatting
Step 4: Verify Installation
pytest # Run all tests pytest -v # Run with verbose output pytest tests/test_permissions.py # Run specific test file pytest tests/test_notebooks.py # Run notebook tests
💡 Pro Tip: The test suite includes automated testing of tutorial notebooks to ensure they stay up-to-date and functional. Make sure you have the required dependencies installed (nbformat, nbconvert, and ipykernel) before running notebook tests.
💡 Pro Tip: We recommend using uv for faster dependency management:
pip install uv uv pip install -e ".[dev,server,display]" # 10x faster than pip!

📝 Contributing Guidelines

Ready to contribute? Check out our:

🛠️ Development Tools

Useful commands for development:

make lint # Run code linters make format # Auto-format code make test # Run all tests make docs # Build documentation

Verify Installation

Confirm that SyftPerm is installed correctly:

python -c "import syft_perm; print(f'SyftPerm {syft_perm.__version__} installed successfully!')"

You should see output like:

SyftPerm 0.2.32 installed successfully!

Test basic functionality:

import syft_perm import tempfile from pathlib import Path # Create a test file test_file = Path(tempfile.mktemp(suffix=".txt")) test_file.write_text("Hello SyftPerm!") # Open with SyftPerm syft_file = syft_perm.open(test_file) syft_file.grant_read_access("test@example.com") print("✅ SyftPerm is working correctly!") # Cleanup test_file.unlink()

Troubleshooting

Python Version Error

Problem: ERROR: Package requires Python >=3.9

Solution: Upgrade to Python 3.9 or higher. Check your version with python --version.

Import Error

Problem: ModuleNotFoundError: No module named 'syft_perm'

Solution: Ensure you're using the correct Python environment. If using virtual environments, activate it first.

Permission Server Won't Start

Problem: Web editor fails to start with FastAPI errors

Solution: Install server dependencies: pip install "syft-perm[server]"

Table Display Issues

Problem: Permission tables show as raw text instead of formatted tables

Solution: Install display dependencies: pip install "syft-perm[display]"

Next Steps

Now that SyftPerm is installed, here's what to do next:

🚀 Quick Start Tutorial

Learn the essentials in 5 minutes with our hands-on quick start guide.

Start Learning

📚 Complete Tutorials

Master advanced features with our comprehensive tutorial series.

View Tutorials