Manual Virtual Environment Setup

This article is for unsupported platforms and macOS, where positron create and positron venv create currently does not work.

Overview

If PyPositron's automatic virtual environment creation doesn't work on your platform, you can manually create a virtual environment for your PyPositron project. The positron create command will handle all other project setup (directories, files, config.json), but you'll need to manually create the virtual environment afterward.

Prerequisites

• Python 3.9 or higher installed
• pip package manager
• PyPositron project already created using positron create

macOS Manual Virtual Environment Setup

PyPositron's automatic venv creation is currently not supported on macOS. After creating your project with positron create, follow these steps to manually add a virtual environment:

Step 1: Navigate to Your Project

# Go to your PyPositron project directory (created by positron create)
cd your_project_name

Step 2: Create Virtual Environment

# Create a virtual environment named 'venv'
python3 -m venv venv

# Alternative: Use specific Python version if needed
python3.11 -m venv venv

Step 3: Activate Virtual Environment

# Activate the virtual environment
source venv/bin/activate

# You should see (venv) or similar at the beginning of your prompt
# Example: (venv) user@macbook your_project_name %

Step 4: Install PyPositron in Virtual Environment

# Upgrade pip first
pip install --upgrade pip

# Install PyPositron
pip install py-positron

Step 5: Test Installation

# Test that PyPositron is installed correctly
python -c "import py_positron; print('PyPositron installed successfully!')"

# Test CLI command
positron --help

Step 6: Running Your App

# Make sure your venv is activated (you should see (venv) in prompt)
source venv/bin/activate

# Run your PyPositron app
positron start

Step 7: Deactivating Virtual Environment

# When you're done working, deactivate the virtual environment
deactivate

Other Unix-like Systems (FreeBSD, OpenBSD, etc.)

For other Unix-like systems where automatic venv creation may not work:

Step 1: Navigate to Your Project

# Go to your PyPositron project directory (created by positron create)
cd your_project_name

Step 2: Check Python Installation

# Check Python version
python3 --version

# Check if venv module is available
python3 -m venv --help

Step 3: Create Virtual Environment

# Create virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

Step 4: Install PyPositron

# Install PyPositron
pip install --upgrade pip
pip install py-positron

# If you encounter issues, try:
pip install --user py-positron

Step 5: Running Your App

# Always activate your venv before working
source venv/bin/activate

# Run your PyPositron app
positron start

Troubleshooting

Common Issues

1. Python venv Module Not Found

Error: No module named venv

Solution:

# Install python3-venv package (Ubuntu/Debian)
sudo apt-get install python3-venv

# Or use virtualenv instead:
pipx install virtualenv
virtualenv venv

2. Virtual Environment Not Activating

Error: source venv/bin/activate doesn't work

Solution:

# Make sure you're in the project directory
pwd
ls -la  # Should see 'venv' directory

# Try full path
source ./venv/bin/activate

# Or check if activation script exists
ls venv/bin/activate

3. PyPositron Command Not Found After Installation

Error: positron: command not found

Solution:

# Make sure venv is activated (should see (venv) or similar in prompt)
source venv/bin/activate

# Try installing again
pip install --upgrade py-positron

# Or use python -m instead:
python -m py_positron.cli start

4. Permission Denied Errors

Error: Permission denied when creating venv

Solution:

# Create venv in a directory you own
mkdir ~/pypositron_projects
cd ~/pypositron_projects
# Run positron create here instead

# Or check directory permissions
ls -la

Quick Reference

Essential Commands

# Create project (run this first)
positron create

# Navigate to project
cd your_project_name

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install PyPositron
pip install py-positron

# Run your app
positron start

# Deactivate when done
deactivate

Platform Support Status

Platform	Automatic Venv	Manual Venv	Status
Windows	✅ Supported	✅ Not Needed	Full Support
Linux	✅ Supported	✅ Fallback Available	Full Support
macOS	❌ Not Supported	⚠️ Untested	Manual Only
FreeBSD	❌ Not Supported	⚠️ Untested	Manual Only
OpenBSD	❌ Not Supported	⚠️ Untested	Experimental

Important Notes

• Project creation - Always use positron create first, then manually add the venv
• Activation required - Always activate your venv before running positron start
• Shell profile - Consider adding activation to your shell profile for convenience

Getting Help

If you encounter issues with manual venv setup:

1. Check Python installation:

   python3 --version
   pip --version
   

2. Verify project structure:

   ls -la  # Should see main/, views/, config.json, etc.
   

3. Test PyPositron import:

   source venv/bin/activate
   python3 -c "import py_positron; print('Success!')"
   

4. Check our troubleshooting guide: troubleshooting.md

5. Report platform-specific issues: GitHub Issues

Remember: This guide is specifically for platforms where automatic virtual environment creation doesn't work. Most users on Windows and Linux won't need this manual process.

Contributing

If you have a machine with an OS that we don't support or haven't tested, you may want to contribute to make your OS supported.