Your First Project

After installing the State Tool you can get started by installing packages you’re interested in working with. Once you have added all your packages, you can then push this a new ActiveState Platform Project, so you can easily collaborate with others, as well as use the full feature set of the platform, including a web based interface to work and collaborate on your project.

Installing a package

By default the State Tool operates on a project in your current working directory. Which is to say, it will look for an activestate.yaml in your current directory or its parent directories and uses the project defined in that file.

If no such activestate.yaml exists, running state install will create a new one in your current working directory. This is important to note, because if you then run another state install command in a different unrelated directory; you will end up with two separate projects.

To install a new package run the following command:

state install pandas[@1.3.1]

Note that the version specification is optional. See the state install reference documentation for more info.

TIP: You can search for specific packages on the Platform using the state search subcommand. See the state search reference documentation for usage information.

Importing Multiple Packages

If your project already has packages defined for a different package manager then odds are you will be able to import these to the Platform by running:

state import requirements.txt 

Some examples of supported package files:

  • requirements.txt (Python)
  • cpanfile (Perl)
  • META.json (Perl)

See the state import reference documentation for usage information.

Adding Platforms

A Platform is essentially an operating system on which you would like your project to run.

By default the State Tool will use your current platform as the target platform for your requests. If you would like to target multiple platforms you can add these manually.

Let’s say you’re working on Linux, but you also want to target Windows. You can do this by invoking the following command.

state platforms add Windows

See the state platforms reference documentation for usage information.

Creating Your Project

Once you’ve installed a few packages you’re now ready to turn your local-only virtual environment into an ActiveState Platform Project. This will allow you to share your virtual environment with other people or different runtime environments (eg. a staging or production environment).

To turn your local virtual environment into a project, run:

state push

Then follow the prompts and instructions on screen.

See the state push reference documentation for usage information.

Activating Your Project

While you can run state install without first activating your virtual environment, in order to actually start working with your virtual environment you’ll need to activate it.

There are several ways of doing this, but they all utilize the state activate command.

See the state activate reference documentation for usage information.

Private Projects (Enterprise Only)

To access private projects in an organization the State Tool must be authenticated against the ActiveState Platform.

state auth

For more information, see the command reference.

Activate by Directory

Change your current working directory to the directory containing your projects’ activestate.yaml (eg. the directory you ran state install in). Then simply run:

state activate

This will activate the project under your current working directory.

If you followed the steps in this guide you will likely want to activate your project using this method.

Activating by Project Name

You can activate a project simply by giving state activate the “namespace” of your project, that is; the owner name followed by the project name, eg. my-username/my-project-name.

To activate using this method, run the following command:

state activate <owner>/<projectName>

If you already had this project checked out locally State Tool will direct you to the correct local directory. If you had not checked it out locally then State Tool will perform a fresh checkout.


When you are finished working with your project, you can deactivate the runtime environment for your project by entering exit or pressing Ctrl+D to return to your regular shell environment.


When you want to work on your project again you can run the same state activate owner/projectName command from any directory and you’ll be switched into an activated state under your project directory. Alternatively you can manually move to the root of your project directory and run state activate without any other arguments.

What’s Next

Now that you have your project set up and the basics configured check out the following sections to further discover what you can do with the State Tool: