Skip to content

Setting Up a Development Environment

Required Dependencies

Support Matrix

Python Version Python 3.8 Python 3.9 Python 3.10
Operating System
Linux 1
macOS (x86_64)
Windows 3
  1. Install nix
  2. Install gh:

    nix-shell -p gh
    
    nix-env -iA gh
    
  3. Fork and clone the ibis repository:

    gh repo fork --clone --remote ibis-project/ibis
    
  4. Set up the public ibis Cachix cache to pull pre-built dependencies:

    nix-shell -p cachix --run 'cachix use ibis'
    
  5. Run nix-shell in the checkout directory:

    cd ibis
    nix-shell
    

    This may take awhile due to artifact download from the cache.

Some optional dependencies for Windows are not available through conda/mamba

  1. python-duckdb and duckdb-engine. Required for the DuckDB backend.
  2. clickhouse-cityhash. Required for compression support in the ClickHouse backend.

Support Matrix

Python Version Python 3.8 Python 3.9 Python 3.10
Operating System
Linux 1
macOS
Windows
  1. Install Miniconda

  2. Install gh

    conda install -c conda-forge gh
    
  3. Fork and clone the ibis repository:

    gh repo fork --clone --remote ibis-project/ibis
    
  4. Create a Conda environment from a lock file in the repo:

    cd ibis
    conda create -n ibis-dev --file=conda-lock/linux-64-3.9.lock
    
    cd ibis
    conda create -n ibis-dev --file=conda-lock/osx-64-3.9.lock
    
    cd ibis
    conda create -n ibis-dev --file=conda-lock/win-64-3.9.lock
    
  5. Activate the environment

    conda activate ibis-dev
    
  6. Install your local copy of ibis into the Conda environment.

    cd ibis
    pip install -e .
    
  7. If you want to run the backend test suite you'll need to install docker-compose:

    conda install docker-compose -c conda-forge
    
  1. Install Mamba

  2. Install gh

    mamba install -c conda-forge gh
    
  3. Fork and clone the ibis repository:

    gh repo fork --clone --remote ibis-project/ibis
    
  4. Create a Conda environment from a lock file in the repo:

    cd ibis
    mamba create -n ibis-dev --file=conda-lock/linux-64-3.9.lock
    
    cd ibis
    mamba create -n ibis-dev --file=conda-lock/osx-64-3.9.lock
    
    cd ibis
    mamba create -n ibis-dev --file=conda-lock/win-64-3.9.lock
    
  5. Activate the environment

    mamba activate ibis-dev
    
  6. Install your local copy of ibis into the Conda environment.

    cd ibis
    pip install -e .
    
  7. If you want to run the backend test suite you'll need to install docker-compose:

    mamba install docker-compose -c conda-forge
    

pip will not handle installation of system dependencies

pip will not install system dependencies needed for some packages such as psycopg2 and kerberos.

For a better development experience see the conda or nix setup instructions.

  1. Install gh

  2. Fork and clone the ibis repository:

    gh repo fork --clone --remote ibis-project/ibis
    
  3. Change directory into ibis:

    cd ibis
    
  4. Install development dependencies

    pip install -r requirements.txt
    
  5. Install ibis in development mode

    pip install -e .
    

Building the Docs

You must set up an environment with Nix as above to build the website and docs.

Then, run:

mkdocs serve

  1. Tested in CI. If this doesn't work for you, please file an issue

  2. Should work but doesn't because upstream is broken. Supported on a best-effort basis. 

  3. Unlikely to ever be supported or no upstream support. 


Last update: 2022-11-02