Skip to main content

Checkout and Activate Projects

This is the comprehensive guide to deploying ActiveState projects on your local machine. If you're just getting started, you may want to begin with the First Steps guide for a streamlined introduction.

After creating your project, you need to deploy the runtime on your machine by checking it out and activating it. You can check out multiple projects or the same project to different locations on your system.

This guide covers:

Different Ways to Use state checkout​

All checkout methods work with your activestate.yaml file, which acts as a configuration file and shortcut to your project. For more information about this file, see the glossary.

Simple Checkout​

To check out your project and download a project folder containing your project's activestate.yaml file to your current working directory:

state checkout <orgname>/<projectname>

For example: state checkout myOrg/Project1

What this does:

  • Creates a project folder in your current directory
  • Downloads the activestate.yaml configuration file
  • The actual runtime files are cached elsewhere on your system
  • Run state projects to see all locations

Checkout to Current Directory​

To download the activestate.yaml file directly into your current working directory:

state checkout <orgname>/<projectname> .

For example: state checkout myOrg/Project1 .

When to use this:

  • Useful for automation scripts
  • Avoids having to navigate into a new project folder
  • Good when you want the configuration in your existing directory

Checkout to Specific Location​

To checkout a project to a specific location on your system:

state checkout <orgname>/<projectname> <location>

For example: state checkout myOrg/Project1 C:/Projects/MyProject

Benefits:

  • Organize projects in specific directories
  • Maintain consistent project structure
  • Easier to find and manage projects

Checkout with Runtime Path​

To download all project files (.dll, .bat, .exe, etc.) to a specific location:

state checkout <orgname>/<projectname> --runtime-path <folder location>

For example: state checkout myOrg/Project1 --runtime-path C:/Perl

When to use this:

  • When you need to know exact file locations
  • For integration with other tools
  • When you prefer a traditional installation structure

Checkout Specific Branch​

To checkout a specific branch of a project:

state checkout --branch <branchname> <org/project> <path>

For example: state checkout --branch experimental myOrg/Project1 ./test-env

Activating Your Project​

After checking out your project, you need to activate it to use the runtime environment.

The state shell command creates an isolated environment for your project:

state shell

From project directory:

  • Navigate to the directory containing your activestate.yaml file
  • Run state shell
  • This activates the project in that directory

From anywhere:

state shell <orgname>/<projectname>

Benefits:

  • Isolated from system packages
  • Safe for experimentation
  • No global environment changes
  • Easy to exit (type exit)

Usage:

# Navigate to project directory
cd my-project

# Start shell environment
state shell

# Your prompt will change to indicate active environment
(my-project) $ python --version
Python 3.9.7

# Exit when done
(my-project) $ exit

Using state use (System-wide Default)​

The state use command sets a project as your system default:

state use <orgname>/<projectname>

Benefits:

  • Available from anywhere on your system
  • No need to activate each time
  • Good for primary development runtime

Commands:

# Set default project
state use myOrg/myproject

# Check current default
state use show

# Remove default
state use reset
caution

Only one project can be set as the system default at a time. Setting a new default will replace the previous one.

Work with Multiple Projects​

You can work with multiple ActiveState projects simultaneously using different strategies.

Multiple Shell Sessions​

Open separate terminal windows for different projects:

Terminal 1:

state shell myorg/project1

Terminal 2:

state shell myorg/project2

Benefits:

  • Complete isolation between projects
  • No conflicts between dependencies
  • Easy to switch contexts

Default + Shell Override​

Use one project as default and override with shells:

# Set primary project as default
state use myorg/main-project

# Override in specific terminal
state shell myorg/experimental-project

When to use:

  • One primary project for most work
  • Occasional use of other projects
  • Want global availability of main runtime

Find Checked Out Projects on Your System​

To see all projects currently available locally:

state projects

Output includes:

  • Project names and organizations
  • Local checkout paths (where activestate.yaml files are)
  • Runtime cache locations (where binaries are stored)
  • Current activation status

Example output:

Organization/Project           Local Checkout Path              Cache Path
example/python-project        /home/user/projects/python      /home/user/.cache/activestate/...
example/data-analysis         /home/user/analysis             /home/user/.cache/activestate/...

Best Practices​

Project Organization​

  • Use descriptive paths - Organize checkouts in logical directories
  • Consistent structure - Maintain similar layouts across projects
  • Document locations - Keep track of where projects are checked out

Activation Strategy​

  • Use shells for development - Safer and more flexible
  • Set defaults sparingly - Only for your primary runtime
  • Test in isolation - Use shells to test changes safely

Multiple Projects​

  • Name terminals clearly - Use terminal titles to track which project
  • Check activation status - Use state use show to verify current default
  • Clean up regularly - Remove unused checkouts to save space

Troubleshooting​

Project Won't Activate​

  1. Verify checkout - Ensure project was checked out successfully
  2. Check authentication - Run state auth --show for private projects
  3. Update State Tool - Ensure you have the latest version
  4. Network connectivity - Initial activation may require internet

Multiple Checkouts Conflict​

If you have the same project checked out multiple times:

  1. Choose specific path - Use full path when running state shell
  2. Remove duplicates - Delete unnecessary checkouts
  3. Use state projects - List all checkouts to identify conflicts

Shell Environment Not Working​

  1. Verify activestate.yaml - Ensure file exists and is valid
  2. Check directory - Make sure you're in the right location
  3. Try absolute command - Use state shell orgname/projectname
  4. Restart terminal - Fresh terminal session may resolve issues

Next Steps​

After successfully checking out and activating your project:

  1. Install packages - Add dependencies to your project
  2. IDE Integration - Connect your project to development tools
  3. Share with team - Collaborate with others
  4. Docker deployment - Containerize your project