Installing OpenAD

Tl;dr

Bash

pip install openad

Bash

openad

Info

When installing on macOS without a virtual environment, you may need to use python3 and pip3 instead of python and pip.

Installing on macOS / Linux

Info

• Contributors: Skip to Installation for Development
• Linux users: Check the Linux Notes
• Poetry: If you prefer Poetry, you can run the setup wizard instead: poetry add openad

1. Before you start
   Ensure you're running Python 3.10.10+ or 3.11 - see Upgrading Python.

   To see what version you are running:

   Bash

   python -V
   

   Note: Due to an issue with one of our dependencies, Python 3.12 is not yet supported.

2. Set up your virtual environment (recommended)

   Bash

   python -m venv ~/ad-venv
   

   Bash

   source ~/ad-venv/bin/activate
   

   Note: Use python3 on macOS.
   Note: To exit the virtual environment, you can run deactivate

3. Install OpenAD

   Bash

   pip install openad
   

4. Continue to Getting Started

Installing on Windows

In order to run OpenAD on Windows 11, you will need to install the Ubuntu WSL package.

1. Verify Windows version
   To check if you are running Windows 11 or later, press Win + R, type "winver", and press Enter. A window will open showing your Windows version.

2. Verify WSL
   To check if you already have WSL installed, run wsl -l -v into the terminal. To see more information about your current version of Ubuntu, run lsb_release -a

3. Install WSL
   Install WSL and create a user called 'openad' or one of your choosing.

   Bash

   wsl --install Ubuntu-22.04
   

   Optional: To setup an Ubuntu Python environment from scratch, continue to Linux Notes

4. Continue to Getting Started

Appendix

Upgrading Python

There's many ways to install or upgrade Python. We'll use pyenv.

1. Install pyenv

   Bash

   curl https://pyenv.run | bash
   

2. Set up your shell environment for Pyenv
   Detailed instructions can be found here. If you're using Zsh, you can run the commands below:

   Bash

   echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
   

   Bash

   echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
   

   Bash

   echo 'eval "$(pyenv init -)"' >> ~/.zshrc
   

3. Reboot your shell
   You can either open a new window or run:

   Bash

   exec $SHELL
   

4. Install Python
   Please note that OpenAD requires Python 3.10.10+ or 3.11.
   Due to an issue with one of our dependencies, Python 3.12 is not yet supported.

   Bash

   pyenv install 3.11
   

5. Activate this version of Python
   If you wish to set this version as the default:

   Bash

   pyenv global 3.11
   

   Alternatively, if you only wish to activate it in the current shell:

   Bash

   pyenv shell 3.11
   

6. Good to know:
   If you're setting up a virtual environment, you need to set the python version before creating the venv.

   Bash

   pyenv shell 3.11
   

   Bash

   python -m venv my_venv
   

   You can see the list of installed versions by running:

   Bash

   pyenv versions
   

   You can see the currently installed version by running:

   Bash

   pyenv version
   

Linux Notes

If you wish to setup an Ubuntu Python environment from scratch, run:

Bash

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11-full
sudo apt install python3-pip
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 100
sudo pip install pip --upgrade

You will need to restart your Linux session before running pip install openad so that the python libraries are in your path.

If you get an error when running init_magic, you may first need to setup the default iPython profile for magic commands.

Bash

ipython profile create